# Cancel a run Source: https://docs.superglue.cloud/api-reference/runs/cancel-a-run /openapi.yaml post /runs/{runId}/cancel # Get download URL for a file artifact Source: https://docs.superglue.cloud/api-reference/runs/get-download-url-for-a-file-artifact /openapi.yaml get /runs/{runId}/files/{fileKey}/download Get a fresh presigned download URL for a specific file artifact. Use this to refresh expired URLs. # Get full run results Source: https://docs.superglue.cloud/api-reference/runs/get-full-run-results /openapi.yaml get /runs/{runId}/results **Enterprise feature.** Fetch the full (non-truncated) results for a run from storage. Returns null data if run result storage is not enabled. # Get run status and metadata Source: https://docs.superglue.cloud/api-reference/runs/get-run-status-and-metadata /openapi.yaml get /runs/{runId} Returns run status, metadata, and result data. Result data may be truncated for large results. Use GET /runs/{runId}/results to fetch the full (non-truncated) data from storage (requires run result storage to be enabled). # List file artifacts for a run Source: https://docs.superglue.cloud/api-reference/runs/list-file-artifacts-for-a-run /openapi.yaml get /runs/{runId}/files List all file artifacts produced by a run's output transform, with fresh presigned download URLs (1 hour TTL). # List runs Source: https://docs.superglue.cloud/api-reference/runs/list-runs /openapi.yaml get /runs # Create a tool Source: https://docs.superglue.cloud/api-reference/tools/create-a-tool /openapi.yaml post /tools # Delete a tool Source: https://docs.superglue.cloud/api-reference/tools/delete-a-tool /openapi.yaml delete /tools/{toolId} # 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 # Update a tool Source: https://docs.superglue.cloud/api-reference/tools/update-a-tool /openapi.yaml put /tools/{toolId} # 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. Also handles webhook challenge/verification patterns inline: - **monday.com, Slack:** POST body `{ challenge: "..." }` → echoes challenge as JSON - **Generic:** POST body `{ verification_token: "...", type: "verification" }` → echoes token as JSON # Handle webhook challenge verification Source: https://docs.superglue.cloud/api-reference/webhooks/handle-webhook-challenge-verification /openapi.yaml get /hooks/{toolId} **Enterprise feature.** Handle webhook challenge/verification requests from external services. GET requests are only supported for challenge verification (not tool execution). Supported challenge patterns: - **Meta/Facebook/WhatsApp:** `?hub.mode=subscribe&hub.challenge=...` → echoes challenge as plain text - **Microsoft Graph:** `?validationToken=...` → echoes token as plain text - **Nylas/generic:** `?challenge=...` → echoes challenge as plain text # Commands Source: https://docs.superglue.cloud/cli/commands Complete reference for all CLI commands and flags ## sg init Interactive setup wizard. Prompts for API key, endpoint, output mode, and config location. ```bash theme={null} sg init ``` No flags — fully interactive. *** ## sg update Update the CLI to the latest version. ```bash theme={null} sg update sg update --check ``` | Flag | Description | | --------- | ----------------------------------------- | | `--check` | Only check for updates without installing | *** ## Tool Commands ### sg tool build Build a new tool from a config file or individual flags. ```bash theme={null} sg tool build --config tool.json sg tool build --id my-tool --instruction "Fetch user data" --steps steps.json ``` | Flag | Description | | --------------------------- | -------------------------------- | | `--config ` | JSON config file or inline JSON | | `--id ` | Tool ID (kebab-case) | | `--instruction ` | Human-readable tool instruction | | `--steps ` | JSON file containing steps array | | `--output-transform ` | JS output transform function | | `--output-schema ` | JSON file for output schema | | `--payload ` | Sample payload JSON | | `--file ` | File reference (repeatable) | Provide either `--config` or `--id` + `--instruction` + `--steps`. ### sg tool run Execute a draft, saved tool, or inline config. ```bash theme={null} sg tool run --tool my-tool --payload '{"userId": "123"}' sg tool run --draft abc123 sg tool run --config '{"id":"inline","instruction":"...","steps":[...]}' sg tool run --config-file tool.json --payload-file payload.json ``` | Flag | Description | | ------------------------ | ---------------------------------- | | `--tool ` | Saved tool ID | | `--draft ` | Draft ID from build | | `--config ` | Inline tool config JSON | | `--config-file ` | Tool config JSON file | | `--payload ` | JSON payload | | `--payload-file ` | JSON payload file | | `--file ` | File reference (repeatable) | | `--include-step-results` | Include raw step results in output | | `--include-config` | Include full tool config in output | Exactly one of `--tool`, `--draft`, `--config`, or `--config-file` is required. ### sg tool edit Edit a tool or draft using JSON Patch operations ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)). ```bash theme={null} sg tool edit --tool my-tool --patches '[{"op":"replace","path":"/instruction","value":"New instruction"}]' sg tool edit --draft abc123 --patches patches.json ``` | Flag | Description | | -------------------------- | ----------------------------------------------------- | | `--tool ` | Saved tool ID | | `--draft ` | Draft ID | | `--patches ` | JSON Patch array (inline or file path) — **required** | One of `--tool` or `--draft` is required. ### sg tool save Persist a draft to the server. ```bash theme={null} sg tool save --draft abc123 sg tool save --draft abc123 --id custom-tool-id ``` | Flag | Description | | ----------------- | -------------------------------------------------------------- | | `--draft ` | Draft ID — **required** | | `--id ` | Custom ID for the saved tool (defaults to the draft's tool ID) | ### sg tool list List all saved tools. ```bash theme={null} sg tool list ``` No flags. ### sg tool find Search tools by query or look up by exact ID. ```bash theme={null} sg tool find "user data" sg tool find --id my-tool sg tool find ``` | Flag | Description | | ---------------- | -------------------- | | `--id ` | Exact tool ID lookup | When called with no arguments or `*`, lists all tools. Otherwise performs a semantic search. *** ## System Commands ### sg system create Create a new system. ```bash theme={null} sg system create --config system.json sg system create --name "My API" --url https://api.example.com --credentials '{"apiVersion":"v2"}' sg system create --name "My API" --id my_api --url https://api.example.com --credential-ownership user ``` | Flag | Description | | ------------------------------------ | -------------------------------------------------------------------------- | | `--config ` | JSON config file | | `--id ` | System ID (derived from `--name` if omitted) | | `--name ` | Human-readable name — **required** unless using `--config` or `--template` | | `--url ` | API URL — **required** unless using `--config` or `--template` | | `--template ` | Template ID (merges template defaults) | | `--instructions ` | Specific instructions | | `--credentials ` | Runtime credentials JSON, including secret values when needed | | `--authentication ` | Authentication config JSON | | `--credential-ownership ` | `organization` or `user` | | `--docs-url ` | Documentation URL to scrape after creation | | `--openapi-url ` | OpenAPI spec URL to fetch after creation | | `--env ` | `dev` or `prod` | `--name` and `--url` must be present in the system definition — provide them as flags, include them in `--config`, or let `--template` auto-fill both. `--id` is derived from `--name` if omitted. ### sg system edit Edit an existing system. ```bash theme={null} sg system edit --id my-api --url https://api-v2.example.com sg system edit --id my-api --credentials '{"api_key":"new-key"}' sg system edit --id my-api --scrape-url https://docs.example.com --scrape-keywords "auth endpoints" ``` | Flag | Description | | ------------------------------------ | --------------------------------- | | `--id ` | System ID — **required** | | `--name ` | New name | | `--url ` | New URL | | `--instructions ` | New instructions | | `--credentials ` | Runtime credentials JSON to merge | | `--authentication ` | Authentication config JSON | | `--credential-ownership ` | `organization` or `user` | | `--scrape-url ` | Documentation URL to scrape | | `--scrape-keywords ` | Space-separated scrape keywords | | `--env ` | `dev` or `prod` | ### sg system list List all systems. ```bash theme={null} sg system list sg system list --mode dev ``` | Flag | Description | | --------------- | --------------------------------------------------------------- | | `--mode ` | Filter by environment: `dev`, `prod`, or `all` (default: `all`) | ### sg system find Search systems by query or look up by exact ID. ```bash theme={null} sg system find "payment" sg system find --id my-api sg system find --id my-api --env prod ``` | Flag | Description | | --------------------- | ---------------------- | | `--id ` | Exact system ID lookup | | `--env ` | `dev` or `prod` | ### sg system call Make an authenticated call through a system (HTTP API, database, or file server). ```bash theme={null} sg system call --url https://api.example.com/users --system-id my-api sg system call --url https://api.example.com/users --method POST --body '{"name":"Jane"}' --system-id my-api sg system call --url postgres://host/db --system-id my-db --body "SELECT * FROM users LIMIT 5" ``` | Flag | Description | | --------------------- | ------------------------------------------------------------- | | `--url ` | Full URL including protocol — **required** | | `--system-id ` | System ID for credential injection | | `--method ` | HTTP method (default: `GET`) | | `--headers ` | HTTP headers JSON | | `--body ` | Request body | | `--file ` | File reference (repeatable) | | `--env ` | `dev` or `prod` | | `--continue-on-error` | Return a failed response envelope instead of exiting non-zero | ### sg system credentials Manage the current user's credentials for systems configured with `credentialOwnership: "user"`. ```bash theme={null} sg system credentials get --system-id my-api sg system credentials set --system-id my-api --credentials '{"api_key":"sk-..."}' sg system credentials clear --system-id my-api ``` | Subcommand | Description | | ---------- | ----------------------------------------------------------------------------------------------------- | | `get` | Get current user's credentials for a user-owned system. Values are masked unless `--reveal` is passed | | `set` | Set current user's credentials from `--credentials ` | | `clear` | Delete current user's credentials | Common flags: | Flag | Description | | --------------------- | ------------------------ | | `--system-id ` | System ID — **required** | | `--env ` | `dev` or `prod` | ### sg system search-docs Search a system's scraped documentation. ```bash theme={null} sg system search-docs --system-id my-api --keywords "authentication oauth" ``` | Flag | Description | | --------------------------- | ------------------------------ | | `--system-id ` | System ID — **required** | | `-k, --keywords ` | Search keywords — **required** | ### sg system oauth Authenticate a system via OAuth. ```bash theme={null} sg system oauth --system-id my-api --scopes "read write" sg system oauth --system-id my-api --scopes "read" --grant-type client_credentials ``` | Flag | Description | | --------------------- | --------------------------------------------------------------- | | `--system-id ` | System ID — **required** | | `--scopes ` | Space-separated OAuth scopes; defaults to system/template value | | `--auth-url ` | OAuth authorization URL (defaults to system/template value) | | `--token-url ` | OAuth token URL (defaults to system/template value) | | `--grant-type ` | `authorization_code` (default) or `client_credentials` | | `--env ` | `dev` or `prod` | *** ## Run Commands ### sg run list List recent tool execution runs. ```bash theme={null} sg run list sg run list --tool my-tool --status success --limit 20 sg run list --source cli,sdk --user user_123 ``` | Flag | Description | | -------------------- | --------------------------------------------------------------------------------------------- | | `--tool ` | Filter by tool ID | | `--status ` | Filter by status: `running`, `success`, `failed`, `aborted` | | `--source ` | Comma-separated request sources | | `--user ` | Filter by user ID | | `--system-id ` | Filter by system ID | | `--limit ` | Max results (default: `10`, max: `50`) | | `--offset ` | Offset for pagination — converted to a page number as `ceil((offset+1)/limit)` (default: `0`) | ### sg run get Get details of a specific run. ```bash theme={null} sg run get run_abc123 ``` Takes a positional `runId` argument. No additional flags. # Overview Source: https://docs.superglue.cloud/cli/overview Install and configure the superglue CLI The superglue CLI (`sg`) lets you build, run, and manage integration tools from the terminal. It connects to your superglue instance (cloud or self-hosted) and supports both interactive and scriptable workflows. ## Installation ```bash theme={null} npm install -g @superglue/cli ``` Verify the install: ```bash theme={null} sg --version ``` ## Setup Run the interactive setup wizard: ```bash theme={null} sg init ``` This prompts for: * **API key** — from your superglue dashboard (Settings → API Keys) * **API endpoint** — defaults to `https://api.superglue.cloud` * **Output mode** — stdout only, or stdout + file * **Config location** — project-local (`.superglue/config.json`) or global (`~/.superglue/config.json`) Alternatively, set environment variables directly: ```bash theme={null} export SUPERGLUE_API_KEY="your-api-key" export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud" ``` ## Configuration Resolution Both API key and endpoint resolve in this order: 1. CLI flag (`--api-key`, `--endpoint`) 2. Environment variable (`SUPERGLUE_API_KEY`, `SUPERGLUE_API_ENDPOINT`) 3. Config file 4. Default (endpoint defaults to `https://api.superglue.cloud`) ## Global Flags These flags work with any command: | Flag | Description | | ------------------ | --------------------------------------------------- | | `--api-key ` | Override API key | | `--endpoint ` | Override API endpoint | | `--json` | Force JSON output (default in non-TTY environments) | | `-V, --version` | Print CLI version | | `-h, --help` | Show help | ## Command Structure ``` sg ├── init Setup wizard ├── update Update CLI ├── tool │ ├── build Build a tool from config │ ├── run Execute a tool │ ├── edit Edit via JSON Patch │ ├── save Persist a draft │ ├── list List saved tools │ └── find Search tools ├── system │ ├── create Create a system │ ├── edit Edit a system │ ├── list List systems │ ├── find Search systems │ ├── credentials Manage current user's system credentials │ ├── call Make authenticated calls │ ├── search-docs Search system docs │ └── oauth OAuth authentication └── run ├── list List execution runs └── get Get run details ``` ## AI Agent Integration Install as a skill for AI coding agents ([35+ agents supported](https://skills.sh)): ```bash theme={null} npx skills add superglue-ai/cli ``` Or target a specific agent: ```bash theme={null} npx skills add superglue-ai/cli -g -a cursor npx skills add superglue-ai/cli -g -a claude-code npx skills add superglue-ai/cli -g -a codex ``` ## Next steps Full reference for every CLI command and flag # 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. # Role-Based Access Control Source: https://docs.superglue.cloud/enterprise/rbac Control who can access which tools and systems with binary allowlists **Enterprise Feature** — RBAC is available on superglue Enterprise plans. [Contact us](https://cal.com/superglue/superglue-demo) to learn more. Role-Based Access Control (RBAC) lets you define **roles** that control which tools and systems users can access. Roles can be assigned to organization members, giving you focused control over your integration layer. ## Core Concepts ### Base Roles Every user has exactly one **base role**. superglue ships with two base roles: | Base role | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | **Admin** | Full access to everything. Bypasses RBAC checks. Cannot be edited. | | **Member** | Default for organization members. Starts with access to all tools and systems. Tool and system allowlists can narrow it. | ### Custom Roles You can create **custom roles** for specific use cases, such as a Sales Team role with access to CRM tools and systems. Custom roles are fully editable and can be assigned on top of a user's base role. ## Allowlists Every role defines two binary allowlists: * **Tools** — which saved tools the role can run * **Systems** — which systems the role can access Each allowlist supports two modes: * `"ALL"` — every current and future resource is allowed * Specific list — only listed resource IDs are allowed ```json theme={null} { "name": "Sales Team", "tools": ["get-contacts", "search-deals", "update-deal"], "systems": ["salesforce", "hubspot"] } ``` If a tool or system is not listed, it is denied. System access is binary by system ID: listed means allowed, omitted means denied. ## Tool And System Dependencies Tool and system allowlists are intentionally entangled: * A tool is effectively visible and runnable only when the user has access to the tool **and** every system referenced by the tool's request steps. * Granting a tool without its required systems means the tool may still be hidden or blocked. * `systems: "ALL"` satisfies every tool system dependency. ## Multi-Role Evaluation Users can have multiple roles: one base role plus any number of custom and personal roles. Resolution is union: | Layer | Semantics | | ------- | ----------------------------------------------------- | | Tools | If any role allows a tool, the tool ID is allowed | | Systems | If any role allows a system, the system ID is allowed | Roles can add access but cannot remove access granted by another assigned role. ## Personal Roles Every user can have a **personal role**: a per-user allowlist that grants individual access on top of base and custom roles. * Each user has at most one personal role * Personal role allowlists are unioned with the user's other roles * Admins can edit personal roles to grant or revoke direct personal access to tools and systems * Use case: giving a single team member access to a sensitive system without creating a shared role Manage personal roles via the **Personal Roles** tab in Access Rules, or the REST API (`POST /v1/users/:userId/personal-role`). ## Auto-Grant On Resource Creation When a user creates a new tool or system, superglue automatically grants it to the creator's personal role: * New tool -> appended to the creator's personal tool allowlist * New system -> appended to the creator's personal system allowlist This keeps users on restricted allowlists able to use the resources they create without adding those resources to a shared base or custom role. ## Managing Roles ### Via The Dashboard 1. Navigate to **Control Panel -> Organization** 2. Open **Access Rules** 3. Use **Org Roles** to create and edit shared roles 4. Use **Personal Roles** to grant per-user tool and system access ### Via The API Roles are represented with binary allowlists: ```json theme={null} { "tools": "ALL", "systems": ["salesforce", "hubspot"] } ``` Only `"ALL"` means open access. Empty arrays, missing fields, or `null` mean no direct access from that role. # 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} ``` ### Using development mode To execute webhooks against development/sandbox system credentials, add the `mode` parameter: ``` POST https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}&mode=dev ``` This is useful for testing webhook integrations with sandbox environments before going live. **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", config: { systemId: "mailchimp", method: "POST", url: "https://api.mailchimp.com/3.0/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", config: { systemId: "vercel", method: "POST", url: "https://api.vercel.com/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 { outputTransform: `(sourceData) => { if (sourceData.type !== 'customer.created') { return { skipped: true, reason: 'Event type not handled' }; } return sourceData.addToMailchimp; }` } ``` ## Tool chaining You can chain tools together so that one tool automatically triggers another when it completes. This is useful for building multi-step workflows where the output of one tool becomes the input of the next. ### How it works When running a tool via the API, use the special `tool:{toolId}` format for the `webhookUrl` option instead of an HTTP URL: ```bash theme={null} curl -X POST "https://api.superglue.ai/v1/tools/fetch-orders/run" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "since": "2025-01-01" }, "options": { "async": true, "webhookUrl": "tool:process-orders" } }' ``` When `fetch-orders` completes: 1. Its output data becomes the input payload for `process-orders` 2. `process-orders` is triggered automatically 3. The chained run has `requestSource: "tool-chain"` ### Viewing chained runs You can filter runs by request source to see tool chain executions: ```bash theme={null} curl "https://api.superglue.ai/v1/runs?requestSources=tool-chain" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Example: ETL pipeline Build a data pipeline where each stage triggers the next: 1. **extract-data** → fetches raw data from source API 2. **transform-data** → cleans and reshapes the data 3. **load-data** → inserts into destination database ```bash theme={null} # Start the pipeline - each tool chains to the next curl -X POST "https://api.superglue.ai/v1/tools/extract-data/run" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "table": "customers" }, "options": { "async": true, "webhookUrl": "tool:transform-data" } }' ``` Configure `transform-data` to chain to `load-data` in its tool configuration or pass it at runtime. Tool chains execute asynchronously. Use the runs API to monitor progress and check for failures at each stage. # CLI + Skills Source: https://docs.superglue.cloud/getting-started/cli-skills Set up AI agents to build and manage superglue tools via the CLI and superglue skill AI coding agents work best when they understand your systems, APIs, and tools. The superglue CLI ships with a **skill** — a structured reference that teaches agents how to use every `sg` command, handle auth, build tools, and debug failures. Install once, works across [35+ agents](https://skills.sh). *** ## Installing the CLI ```bash theme={null} npm install -g @superglue/cli ``` ### Setup **Interactive setup:** ```bash theme={null} sg init ``` Prompts for your API key (get one at [app.superglue.cloud/admin](https://app.superglue.cloud/admin?view=api-keys)), endpoint, and output preferences. **Environment variables (CI, AI agents, non-interactive):** ```bash theme={null} export SUPERGLUE_API_KEY="your-api-key" export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud" # optional, this is the default ``` **Verify:** `sg system list` — if you see `fetch failed` or auth errors, double-check your API key and endpoint. *** ## Installing the Skill The skill gives your AI agent full CLI knowledge — commands, auth patterns, tool schemas, debugging, and deployment. Install once and the agent references it automatically. ### Universal Install (all agents) ```bash theme={null} npx skills add superglue-ai/cli ``` Auto-detects your installed agents. Target a specific agent with `-g -a `: ```bash theme={null} npx skills add superglue-ai/cli -g -a claude-code npx skills add superglue-ai/cli -g -a codex npx skills add superglue-ai/cli -g -a cursor ``` ### Agent-Specific Install **From the Anthropic marketplace:** ```bash theme={null} /plugin install superglue@claude-plugins-official ``` **Or load from local install:** ```bash theme={null} claude --plugin-dir $(npm root -g)/@superglue/cli ``` **Via the skill installer:** ``` $skill-installer --repo superglue-ai/cli --path skills/superglue ``` **Or manually:** ```bash theme={null} cp -r $(npm root -g)/@superglue/cli/skills/superglue ~/.agents/skills/superglue ``` Check it into your repo at `.agents/skills/superglue/` so the whole team gets it. ```bash theme={null} cp -r $(npm root -g)/@superglue/cli/skills/superglue .cursor/skills/superglue ``` Or global: `cp -r $(npm root -g)/@superglue/cli/skills/superglue ~/.cursor/skills/superglue` *** ## What the Skill Provides * **All CLI commands** with flags, options, and usage patterns * **Authentication patterns** — credential placeholders, OAuth flows, header formats * **Tool configuration schema** — step configs, data selectors, transforms, pagination * **Debugging workflows** — common errors, `--include-step-results`, `sg system call` for isolation * **Deployment patterns** — SDK, REST API, webhooks (via `references/integration.md`) * **Specialized references** for databases, file servers, and transforms (loaded on demand) *** ## Adding Project-Specific Context The skill teaches the AI *how* to use superglue. Add a section to your project's AI config file (`CLAUDE.md`, `AGENTS.md`, or `.cursorrules`) so it knows to use the skill and discover your setup dynamically: ```markdown theme={null} ## Using Superglue When working with superglue tools — via the CLI, SDK, or REST API: 1. Invoke the superglue skill and read the SKILL.md file before running any sg command 2. Read the relevant reference files for the task (e.g. http, postgres, file-handling, integration) 3. Ensure the CLI is configured (sg init has been run or env vars are set) 4. Run sg system list and sg tool list to discover the current setup before building or modifying anything 5. Never hardcode system IDs or tool IDs — always discover them dynamically ``` *** ## Best Practices ### Always test systems before building tools Have the agent run `sg system call` to verify auth and see the actual response shape before constructing a tool config: ```bash theme={null} sg system call --system-id stripe \ --url "https://api.stripe.com/v1/customers?limit=2" \ --headers '{"Authorization":"Bearer <>"}' ``` ### Use `--include-step-results` when debugging Shows the raw API response from each step — pinpoints whether the issue is auth, the endpoint, or a transform: ```bash theme={null} sg tool run --draft --payload '{}' --include-step-results ``` ### Never paste secrets into chat Use `--sensitive-credentials` when creating systems via the CLI so secrets are prompted securely: ```bash theme={null} sg system create --id my_api --url https://api.example.com \ --credentials '{"client_id":"abc"}' \ --sensitive-credentials client_secret,api_key ``` *** ## LLM-Readable Documentation For agents that don't support skills, we provide full docs in LLM-friendly formats: | File | URL | Purpose | | ------------- | ----------------------------------------------------------- | ---------------------------------- | | **Index** | [llms.txt](https://docs.superglue.cloud/llms.txt) | Lightweight index of all pages | | **Full docs** | [llms-full.txt](https://docs.superglue.cloud/llms-full.txt) | Complete documentation in one file | If your tool can fetch URLs — give it the URL. If it requires file uploads — download [llms-full.txt](https://docs.superglue.cloud/llms-full.txt) and upload directly. *** ## Support & Resources * [skills.sh](https://skills.sh) — Install the superglue skill for any AI agent * [CLI Reference](https://github.com/superglue-ai/cli) — Full command documentation * [Discord Community](https://discord.gg/vUKnuhHtfW) — Get help from other developers * [GitHub Issues](https://github.com/superglue-ai/cli/issues) — Report bugs or request features # 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, Redis instances, 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). ## Runtime superglue is not just a tool builder, it's the execution environment where your tools run. When you execute a tool, superglue handles the entire data pipeline: making API calls, resolving credentials, managing retries and rate limiting, and logging results. You don't need to host your own workers, manage queues, or set up cron infrastructure. Tools can be triggered through multiple access points: the REST API, the TypeScript and Python SDKs, Model Context Protocol (MCP) for AI agents, the CLI, or directly from the UI. For automated execution, superglue supports cron-based schedules and incoming webhooks. Every execution, whether triggered manually or on a schedule, produces a run record with step-by-step logs, timing, and full request/response details. To learn more about running tools, see the [deploying a tool](/guides/deploying-a-tool) guide. ## Agents Definitions of agents vary. When mentioning agents in superglue, we are referring to a chat-based interface to 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 Build production-grade integrations in minutes. superglue is an agentic integration platform. superglue agents write, monitor and repair production-grade enterprise integrations from natural language prompts. ## 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. 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. superglue executes your tools remotely. No servers, queues, or cron jobs on your side. Built-in retries, rate limiting, credential management, and full observability for every execution. *** ## How superglue works Add REST, GraphQL, SOAP, Postgres databases, Redis, 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. superglue is not just a tool builder, it's a runtime. Tools execute on superglue's infrastructure, not yours. Trigger runs via the REST API, SDK, MCP, CLI, or the UI, or automate them on a schedule or via webhooks. Credentials are resolved server-side and never leave superglue. Every execution produces a full run record with step-by-step logs, timing, and error details. *** ## 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) # 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 one of the system icons (Slack, Stripe, GitHub, etc.) or describe the system you want to connect in the agent chat: Superglue agent interface The agent will guide you through authentication and configuration. Describe what you need — the agent will set up your tool, test it, and let you review before saving. 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, a PostgreSQL database, and an LLM API key (OpenAI, Anthropic, or Gemini) For full environment setup, see [Production Setup](#production-setup) below or 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 3001:3001 \ -p 3002:3002 \ superglueai/superglue:latest ``` * **Dashboard:** [http://localhost:3001](http://localhost:3001) * **REST API:** [http://localhost:3002](http://localhost:3002) *** ### Local Development ```bash theme={null} git clone https://github.com/superglue-ai/superglue.git cd superglue cp .env.example .env ``` Edit `.env` with your configuration, then: ```bash theme={null} npm install npm run dev ``` *** ### Production Setup For production deployments: ```env theme={null} # =================== # REQUIRED # =================== # Server endpoints (required for web dashboard to connect) API_ENDPOINT=https://your-domain.com:3002 SUPERGLUE_APP_URL=https://your-domain.com:3001 # Authentication (required) AUTH_TOKEN=your-api-key-that-you-use-to-auth # LLM Provider: OPENAI, ANTHROPIC, GEMINI, BEDROCK, VERTEX, or AZURE LLM_PROVIDER=ANTHROPIC # Provide the API key and model for your chosen provider: # ANTHROPIC_API_KEY=sk-ant-xxxxx # ANTHROPIC_MODEL=claude-sonnet-4-5 # GEMINI_API_KEY=your-gemini-key # GEMINI_MODEL=gemini-2.5-flash # OPENAI_API_KEY=sk-proj-xxxxx # OPENAI_MODEL=gpt-5.2 # PostgreSQL (required) POSTGRES_HOST=your-postgres-host POSTGRES_PORT=5432 POSTGRES_USERNAME=superglue POSTGRES_PASSWORD=secure-password POSTGRES_DB=superglue # Uncomment for local/unsecured postgres: # POSTGRES_SSL=false # Credential encryption (HIGHLY recommended) # Generate a strong key: openssl rand -hex 32 MASTER_ENCRYPTION_KEY=your-32-byte-encryption-key # =================== # OPTIONAL # =================== # Web search in agent # TAVILY_API_KEY=your-tavily-key # Workflow scheduling (only enable on a single instance) # START_SCHEDULER_SERVER=false ``` *** ### File Storage File storage (S3 or MinIO) is required for **system documentation** — including URL scraping, OpenAPI spec fetching, and file uploads. Without it, tools can still be created and executed, but systems won't have documentation context for the AI agent. Add to your `.env`: ```env theme={null} FILE_STORAGE_PROVIDER=aws AWS_ACCESS_KEY_ID=your-access-key AWS_SECRET_ACCESS_KEY=your-secret-key AWS_REGION=us-east-1 AWS_BUCKET_NAME=your-bucket-name AWS_BUCKET_PREFIX=raw ``` Uploaded files (PDFs, CSVs, etc.) are stored in S3 and automatically parsed after upload. [MinIO](https://min.io) is an S3-compatible object store you can run alongside superglue. Add to your `.env`: ```env theme={null} FILE_STORAGE_PROVIDER=minio S3_ENDPOINT=http://minio:9000 S3_PUBLIC_ENDPOINT=http://localhost:9000 MINIO_ROOT_USER=minioadmin MINIO_ROOT_PASSWORD=change-me-in-production MINIO_BUCKET_NAME=superglue-files MINIO_BUCKET_PREFIX=raw ``` Uploaded files are stored in MinIO and automatically parsed after upload. *** ## 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 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 and data stores by providing connection details. Supported types include PostgreSQL, MSSQL, Redis, and FTP/SFTP servers. ### Configuration **PostgreSQL** requires a connection URL in the format `postgresql://<>:<>@<>:<>/<>` with credentials for `user`, `password`, `host`, `port`, and `database`. **MSSQL** requires a connection URL in the format `mssql://<>:<>@<>:<>/<>` with credentials for `user`, `password`, `host`, `port`, and `database`. For Azure SQL, use the fully qualified server name (e.g., `myserver.database.windows.net`). **Redis** requires a connection URL in the format `redis://<>:<>@<>:<>/<>` (or `rediss://` for TLS). The database number (0-15) is optional and defaults to 0. **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 MSSQL 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 ## Development and production environments **Enterprise Feature** — Multi-environment systems are available on superglue Enterprise plans. Systems can be configured with separate development and production environments. This allows you to test integrations with sandbox/staging credentials before deploying to production. ### How it works * Each system can have a **dev** and **prod** version with the same ID but different credentials * When running tools, specify `mode: "dev"` or `mode: "prod"` to control which system credentials are used * Systems without a linked environment work in both modes (standalone systems) ### Creating environment-specific systems 1. Create your production system as normal 2. Open the system and click **Add Development Environment** 3. Configure development-specific credentials (e.g., sandbox API keys) 4. Both environments share the same documentation and configuration, only credentials differ ```bash theme={null} # Create production system curl -X POST https://api.superglue.ai/v1/systems \ -H "Authorization: Bearer $API_KEY" \ -d '{ "id": "stripe", "name": "Stripe", "url": "https://api.stripe.com", "environment": "prod", "credentials": { "apiKey": "sk_live_..." } }' # Create linked development system curl -X POST https://api.superglue.ai/v1/systems \ -H "Authorization: Bearer $API_KEY" \ -d '{ "id": "stripe", "name": "Stripe", "url": "https://api.stripe.com", "environment": "dev", "credentials": { "apiKey": "sk_test_..." } }' ``` ### Running tools in different modes ```typescript theme={null} import { runTool } from "@superglue/client"; // Use production credentials (default) await runTool("my-tool", { inputs: { ... }, options: { mode: "prod" } }); // Use development/sandbox credentials await runTool("my-tool", { inputs: { ... }, options: { mode: "dev" } }); ``` ### Environment resolution When a tool runs with a specific mode: 1. **Linked systems**: If a system has both dev and prod versions, the matching environment is used 2. **Standalone systems**: Systems without a linked counterpart work in both modes 3. **Default**: If no mode is specified, `prod` is used ## IP whitelisting If your system requires IP whitelisting (firewall rules, security groups, etc.), superglue's outbound IPs are `34.234.12.178` and `18.198.191.215`. Add both to your allowlist. ## 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 instruction: "Fetch customer data from Stripe", // Human-readable description dataSelector: "(sourceData) => { return [\"one\", \"two\"]}", // The data selector for the current step config: { systemId: "stripe", // Which system to use method: "POST", // HTTP method url: "https://api.stripe.com/v1/customers", // Full API endpoint URL queryParams: {}, // URL query parameters headers: { "Authorization": "Bearer <>" }, // 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} { dataSelector: `(sourceData) => { const items = sourceData.fetchItems.results || []; const excludeIds = sourceData.excludeIds || []; return items.filter(item => !excludeIds.includes(item.id)); }`; } ``` Whether a step loops through more than one request is determined by the data selector. If the data selector returns an Array, the request will execute once for each item in that array. The item of the current iteration is available in the config as `<>` or accessible in code via `sourceData.currentItem`. ### Output transform Shape the final output of the entire tool: ```typescript theme={null} { outputTransform: `(sourceData) => { const customers = sourceData.getCustomers.data || []; const updated = sourceData.updateCustomers || []; return { success: true, total: customers.length, updated: updated.length, results: updated.map(r => ({ id: r.currentItem.id, status: r.data.status })) }; }`; } ``` ## Transform steps Transform steps allow you to reshape data between API calls without making an external request. Use them when you need complex data transformations that don't fit in a `dataSelector`. ### Basic structure ```typescript theme={null} { id: "formatCustomerData", instruction: "Format customer data for the next API call", config: { type: "transform", transformCode: "(sourceData) => sourceData.getCustomers.data.map(c => ({ id: c.id, name: c.fullName, email: c.contactEmail }))" } } ``` ### When to use transform steps * **Complex data reshaping** between API calls * **Aggregating data** from multiple previous steps * **Filtering or sorting** data before the next request * **Preparing payloads** in a specific format ### Accessing transform results Transform step results are wrapped in the same `{ currentItem, data, success }` envelope as request steps: ```typescript theme={null} // In a subsequent step — access the transformed data via .data { body: "<<(sourceData) => JSON.stringify(sourceData.formatCustomerData.data)>>" } ``` Transform steps do NOT have `systemId`, `url`, `method`, `headers`, `body`, or `pagination` fields. They only have `type: "transform"` and `transformCode`. ## Special systems ### PostgreSQL Query databases using the postgres\:// URL scheme: ```typescript theme={null} { id: "queryDatabase", config: { systemId: "postgres_db", url: "postgres://<>:<>@<>:5432/<>", body: { query: "SELECT * FROM users WHERE status = $1 AND created_at > $2", params: ["active", "<<(sourceData) => sourceData.startDate>>"] } } } ``` **Always use parameterized queries** with `$1`, `$2`, etc. placeholders to prevent SQL injection. Provide values in the `params` array, which can include static values or `<<>>` expressions. ### Redis Execute Redis commands using the redis\:// (or rediss\:// for TLS) URL scheme: ```typescript theme={null} { id: "getUserProfile", config: { systemId: "redis_cache", url: "redis://<>:<>@<>:6379/0", body: { command: "HGETALL", args: ["<<(sourceData) => `user:${sourceData.userId}`>>"] } } } ``` The body takes a `command` string and optional `args` array. You can also pass an array of commands to execute them as a pipeline in a single round-trip: ```typescript theme={null} body: [ { command: "GET", args: ["user:123:name"] }, { command: "HGETALL", args: ["user:123"] } ] ``` ### FTP/SFTP Access files on FTP servers: ```typescript theme={null} { id: "listFiles", config: { systemId: "ftp-server", url: "sftp://<>:<>@<>:22/data", body: { operation: "list", path: "/reports" } } } ``` **Supported operations:** * `list` - List directory contents * `get` - Download file (auto-parses CSV/JSON/XML) * `put` - Upload file * `delete` - Delete file * `rename` - Rename/move file * `mkdir` - Create directory * `rmdir` - Remove directory * `exists` - Check if file exists * `stat` - Get file metadata ## Error handling 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. ## 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. Tool input ### 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 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 Step output 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 Step output 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 superglue isn't just where you build tools, it's where they run. When you execute a tool, superglue handles the infrastructure: making API calls, resolving credentials server-side, managing retries and rate limiting, and logging every step. You don't need servers, queues, or cron jobs on your side. Trigger tool runs on-demand, automate them on a schedule, or react to external events via webhooks. All through the same managed runtime. Execute tools programmatically from your codebase using the TypeScript or Python SDK, or call the REST API directly. Give AI agents direct access to execute tools via Model Context Protocol in Cursor, Claude, and other MCP clients. Automate execution with cron schedules or trigger runs from external services like Stripe, GitHub, or Shopify. Execute tools directly from the tool details page: Step input 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. Chain tools together so one tool's output automatically triggers another tool. ## Tool chaining Chain multiple tools together to build multi-step workflows. When one tool completes, it can automatically trigger another tool with its output as input. ```typescript theme={null} // Run a tool that chains to another tool when complete const { data: run } = await runTool("fetch-orders", { inputs: { since: "2025-01-01" }, options: { async: true, webhookUrl: "tool:process-orders", // Triggers process-orders with fetch-orders output }, }); ``` The chained tool run will have `requestSource: "tool-chain"`. See the [webhooks documentation](/enterprise/webhooks#tool-chaining) for more details. # Let agents act on any system without pre-built tools Source: https://docs.superglue.cloud/guides/dynamic-tool-building Set up systems on superglue once, empower your agent to handle the rest. When you build an in-app agent today, every action it can take has to be defined in advance. Someone maps the endpoints, builds the connector, names the tool. The agent is only as capable as whatever you pre-built for it. That's a hard ceiling on your agent's capabilities. superglue removes this ceiling. Connect a system once. Your agent can interact with it at runtime, querying, updating, navigating, based on what the user actually asks, without defining every integration use case first or worrying about authentication. ## What this unlocks A user can ask "get my last 5 invoices" or "update the billing email for customer X", and the agent assembles the right API call for each, using the same superglue system. No one had to anticipate either request. Every runtime execution creates a run record. You see the full tool config, which APIs were called, what came back, success or failure, and timing. Same dashboard whether the tool was pre-built or assembled on the fly. The agent references credentials with `<>` syntax, resolved server-side at execution time. API keys, OAuth tokens, database passwords: all stay in superglue. OAuth tokens refresh automatically. Restricted API keys limit access to specific systems. User-owned credentials control per-user reach. Environment isolation separates dev and prod. All enforced at the system level. *** ## How it works under the hood Your agent uses the superglue CLI (`sg`) and the [superglue skill](/getting-started/cli-skills#installing-the-skill). This skill teaches your agent all superglue CLI commands, auth patterns, tool schemas, and data flow conventions. ```bash theme={null} sg system list ``` The agent queries real API docs stored in superglue rather than guessing endpoint shapes. ```bash theme={null} sg system search-docs --system-id stripe -k "list invoices" ``` A single command, no persistence. No `build`, no `save`, no draft files. ```bash theme={null} sg tool run --config '{ "id": "get-invoices", "instruction": "Fetch recent Stripe invoices for a customer", "steps": [{ "id": "list-invoices", "config": { "systemId": "stripe", "url": "https://api.stripe.com/v1/invoices?customer=<>&limit=5", "method": "GET", "headers": {"Authorization": "Bearer <>"} } }] }' --payload '{"customerId": "cus_abc123"}' ``` The agent returns the result to the user and moves on. *** ## Setup Follow the [CLI + Skills](/getting-started/cli-skills) guide to install the CLI and skill for your agent framework. Set environment variables for your agent's runtime: ```bash theme={null} export SUPERGLUE_API_KEY="your-api-key" export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud" ``` Limit what the AI agent can access via superglue role-based access patterns. Set up the systems your agent should be able to reach: APIs, databases, file servers. ```bash theme={null} sg system create --name "Stripe" --template stripe \ --credentials '{"api_key":"sk_live_xxx"}' \ --docs-url "https://docs.stripe.com/api" ``` See [Creating a system](/guides/creating-a-system) for more details. Add detailed instruction on which systems to use, which tools to run and which CLI commands to invoke to your agent's system prompts and Markdown reference files. *** ## Next steps CLI installation, skill setup, and project-specific agent configuration Full reference for `sg tool run --config` and all other commands Control tool and system access with roles and allowlists Monitor and debug all tool executions, including inline runs # Secure Gateway Source: https://docs.superglue.cloud/guides/secure-gateway Connect superglue to private data sources that aren't publicly accessible The superglue Secure Gateway enables connections from superglue Cloud to data sources that aren't publicly accessible. Deploy a lightweight agent in your private environment, and it establishes a secure outbound connection to superglue - no inbound firewall rules required. ## Use Cases * **On-premises servers** behind corporate firewalls * **Cloud VPCs** (AWS, Azure, GCP) without public endpoints * **Kubernetes clusters** with internal-only services * **Development environments** and localhost * **Any system** that only allows outbound connections Common data sources: * Internal REST APIs * Databases (PostgreSQL, MSSQL) in private subnets * Windows file shares (SMB) on corporate networks * SFTP servers behind firewalls ## How It Works The gateway agent runs in your private environment and establishes an outbound WebSocket connection to superglue Cloud. When a tool needs to access a private system, superglue routes the request through the gateway. Secure Gateway Architecture **Key benefits:** * No inbound firewall rules required * All traffic encrypted via TLS * Agent only exposes explicitly configured targets * Credentials stay in your environment ## Installation ### Download Pre-built Binary First, check your system architecture: ```bash theme={null} uname -m ``` Then download the appropriate binary: ````bash curl -L https://downloads.superglue.cloud/superglue-gateway-linux-x86_64 -o theme={null} superglue-gateway && chmod +x superglue-gateway ``` ```bash curl -L https://downloads.superglue.cloud/superglue-gateway-linux-arm64 -o superglue-gateway && chmod +x superglue-gateway ``` ```powershell Invoke-WebRequest -Uri https://downloads.superglue.cloud/superglue-gateway-windows.exe -OutFile superglue-gateway.exe ```` ### Build from Source If you prefer to build from source (requires Go 1.21+): ```bash theme={null} git clone https://github.com/superglue-ai/superglue.git cd superglue/tunnel-agent go build -o superglue-gateway . ``` ## Configuration Create a `config.yaml` file with your settings: ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: internal_api: "192.168.1.10:8080" ``` ```yaml theme={null} tunnel_id: "aws-prod" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: # Private ALB or internal service internal_alb: "internal-alb-123456.us-east-1.elb.amazonaws.com:80" ``` ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: postgres: "192.168.1.50:5432" ``` ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: mssql: "192.168.1.50:1433" # Or for Azure SQL: # azure_sql: "myserver.database.windows.net:1433" ``` ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: sftp_server: "192.168.1.60:22" ``` ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" targets: file_share: "192.168.1.100:445" ``` ```yaml theme={null} tunnel_id: "acme-corp" server_url: "wss://api.superglue.cloud/ws/tunnels" api_key: "sg_your_api_key_here" # You can expose multiple targets through a single gateway targets: internal_api: "192.168.1.10:8080" postgres: "192.168.1.50:5432" file_share: "192.168.1.100:445" ``` ### Configuration Options | Field | Description | Required | | ------------ | --------------------------------------------------------------------------------------- | -------- | | `tunnel_id` | Unique identifier for this gateway connection. Appears in superglue dashboard. | Yes | | `server_url` | superglue WebSocket endpoint. Use `wss://api.superglue.cloud/ws/tunnels` for hosted. | Yes | | `api_key` | API key from your superglue dashboard | Yes | | `targets` | Map of target names to `host:port` addresses. Each target becomes selectable in the UI. | Yes | ### Getting an API Key 1. Log in to your [superglue dashboard](https://app.superglue.cloud) 2. Go to **Settings** > **API Keys** 3. Click **Create API Key** 4. Copy the key and add it to your `config.yaml` ## Running the Agent ### Manual Start `bash ./superglue-gateway -config /path/to/config.yaml ` `powershell .\superglue-gateway.exe -config C:\path\to\config.yaml ` ### Debug Mode For troubleshooting connection issues, run with the `-debug` flag to enable verbose logging: `bash ./superglue-gateway -config /path/to/config.yaml -debug ` `powershell .\superglue-gateway.exe -config C:\path\to\config.yaml -debug ` Debug mode shows: * WebSocket connection status and handshake details * Incoming tunnel requests with target information * Data channel establishment * TCP connection attempts to local targets * SMB protocol messages (when connecting to Windows shares) * Bytes transferred through the tunnel ### Run in Background To run the agent in the background so it persists after closing your terminal: ```bash theme={null} nohup ./superglue-gateway -config config.yaml > gateway.log 2>&1 & ``` Check if running: `pgrep -a superglue-gateway`. Check logs: `tail -f gateway.log`. Stop: `pkill superglue-gateway`. ### Run as a systemd Service (Linux) 1. Create a service file `/etc/systemd/system/superglue-gateway.service`: ```ini theme={null} [Unit] Description=superglue Gateway Agent After=network.target [Service] Type=simple User=superglue WorkingDirectory=/opt/superglue-gateway ExecStart=/opt/superglue-gateway/superglue-gateway -config /opt/superglue-gateway/config.yaml Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` 2. Enable and start the service: ```bash theme={null} sudo systemctl daemon-reload sudo systemctl enable superglue-gateway sudo systemctl start superglue-gateway ``` 3. Check status: ```bash theme={null} sudo systemctl status superglue-gateway sudo journalctl -u superglue-gateway -f ``` ### Run as a Windows Service 1. Install [NSSM (Non-Sucking Service Manager)](https://nssm.cc/download): ```powershell theme={null} nssm install SuperglueGateway C:\superglue\superglue-gateway.exe -config C:\superglue\config.yaml nssm start SuperglueGateway ``` 2. Check status: ```powershell theme={null} nssm status SuperglueGateway ``` 3. View logs: ```powershell theme={null} nssm get SuperglueGateway AppStdout ``` ### Run in AWS (EC2 / ECS) For AWS VPC access, deploy the agent on an EC2 instance or ECS task within the VPC: ```bash theme={null} # Check your architecture first uname -m # x86_64 or aarch64 # Download the correct binary (x86_64 for most EC2, arm64 for Graviton) curl -L https://downloads.superglue.cloud/superglue-gateway-linux-x86_64 -o superglue-gateway && chmod +x superglue-gateway # Or for ARM/Graviton instances: # curl -L https://downloads.superglue.cloud/superglue-gateway-linux-arm64 -o superglue-gateway && chmod +x superglue-gateway ./superglue-gateway -config config.yaml ``` The agent only needs outbound HTTPS (port 443) access to `api.superglue.cloud`. ## Set up your Private System in Superglue Dashboard Once your gateway agent is running and connected: 1. Go to **Systems** in your superglue dashboard 2. Click **Add System** and select **Private System** 3. Select your connected gateway from the list 4. Choose the target endpoint you want to use 5. Configure authentication (API keys, etc.) if needed 6. Add documentation for the system 7. Save the system If no gateways appear in the list, verify that: - The gateway agent is running and connected - The API key is valid - The `tunnel_id` matches what you expect ## Troubleshooting ### Gateway won't connect * Verify your API key is correct * Check that outbound WebSocket connections (port 443) are allowed * Ensure the `server_url` is correct for your superglue instance ### Target connection fails * Verify the target address is reachable from the gateway host * Check firewall rules / security groups between the gateway and target * Test connectivity: `nc -zv ` ### Connection drops frequently * Check network stability between gateway and superglue cloud * Review gateway logs for specific error messages * Ensure no proxy/firewall is terminating idle connections ## Security Considerations * The gateway only exposes explicitly configured targets * All traffic is encrypted via TLS (WebSocket Secure) * The gateway initiates outbound connections only (no inbound ports needed) * API keys should be kept secure and rotated periodically * Consider running the gateway with minimal privileges * In AWS, use IAM roles and security groups to restrict gateway access # 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 `outputTransform` 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 ); }; ``` ### Output 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 MCP Source: https://docs.superglue.cloud/mcp/using-the-mcp Use saved superglue tools from MCP-compatible clients superglue exposes saved tools through [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). MCP clients can discover available tools, inspect their input schemas, and execute them directly. MCP exposes saved tool discovery and execution. It does not create systems, edit tools, or manage access rules. ## Endpoint Use the MCP endpoint shown in the Deploy modal for your environment. | Environment | Endpoint | | --------------- | ---------------------------------- | | superglue Cloud | `https://api.superglue.cloud/mcp` | | Self-hosted | `https://your-api.example.com/mcp` | The MCP endpoint is the API endpoint with `/mcp` appended. Enterprise deployments can also expose named MCP servers from **Control Panel → MCP Servers**. Named servers have their own endpoint: ```text theme={null} https://your-api.example.com/mcp/{orgId}/{serverName} ``` Use named servers when you want to export a specific set of saved tools instead of the default all-tools endpoint. Named servers can also be managed from the CLI: ```bash theme={null} sg mcp list sg mcp create --name sales-tools --tool get_customer --tool create_invoice sg mcp edit --id --add-tool another_tool ``` For self-hosted instances, configure the CLI with that instance's API endpoint: ```bash theme={null} export SUPERGLUE_API_ENDPOINT="https://your-api.example.com" export SUPERGLUE_API_KEY="your-api-key" ``` ## Client Config For clients that support remote HTTP MCP servers: ```json theme={null} { "mcpServers": { "superglue": { "type": "http", "url": "https://api.superglue.cloud/mcp" } } } ``` Claude Code can add the same server directly: ```bash theme={null} claude mcp add --transport http superglue https://api.superglue.cloud/mcp ``` Use your own deployment endpoint instead of the Cloud endpoint when running self-hosted superglue. ## Authentication The default `/mcp` endpoint accepts the same superglue API keys used by the REST API. API keys can be restricted by access rules and revoked from the superglue app. Enterprise deployments also support MCP OAuth for clients that implement the MCP authorization flow. In that setup, the MCP server advertises protected-resource metadata, dynamic client registration, token, JWKS, and userinfo endpoints; authorization opens the web app for sign-in and consent. Named MCP servers support two authentication modes: * **OAuth Login**: each MCP user logs into their own superglue account through the MCP OAuth flow. * **API key**: the MCP client sends `Authorization: Bearer ` and authenticates as the MCP server creator. The key must be active and assigned to that creator. API-key named servers disable MCP OAuth discovery and do not expose the `authenticate` helper tool. ## Available Tools MCP exposes saved tools that the authenticated user or API key can access. Tool names are derived from saved tool ids, and each tool uses its configured input schema. Named MCP servers store a selected list of tool ids, but RBAC is still enforced at connection and execution time. The callable tool set is the intersection of the named server's selected tools and the authenticated user's or API key owner's allowed tools and systems. MCP-triggered executions create normal superglue runs, so they appear in run history and follow the same access rules as executions started from the app or API. ## Next Steps * Create or edit tools in the superglue app. * Copy your deployment-specific MCP endpoint from the Deploy modal, or create a named server in **Control Panel → MCP Servers**. * Use **Export** on a named server to download setup configs for Langdock, Claude Code, Cursor, and Codex. * Add the server to your MCP client using API key auth or Enterprise OAuth. # 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", mode: "prod", // or "dev" for sandbox credentials }, 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", mode="prod" # or "dev" for sandbox credentials ), 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 * `mode` - Execution mode: `"prod"` (default) or `"dev"` for sandbox credentials * `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 either request operations (HTTP/HTTPS, Postgres, FTP/SFTP) or transform operations (data transformation). ```typescript TypeScript theme={null} // Request step (API calls) interface RequestStepConfig { type?: "request"; url: string; method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; systemId: string; queryParams?: Record; headers?: Record; body?: string; pagination?: Pagination; } // Transform step (data transformation) interface TransformStepConfig { type: "transform"; transformCode: string; // JavaScript function: (sourceData) => transformedData } interface ToolStep { id: string; config: RequestStepConfig | TransformStepConfig; instruction?: string; dataSelector?: string; modify?: boolean; failureBehavior?: "fail" | "continue"; } ``` ```python Python theme={null} from superglue_client.models import ToolStep, ToolStepMethod class ToolStep: id: str config: RequestStepConfig | TransformStepConfig instruction: str | None data_selector: str | None modify: bool | None failure_behavior: ToolStepFailureBehavior | None ``` **Common Fields:** * `id` - Unique identifier * `config` - Step configuration (request or transform) * `instruction` - What this step does * `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 **Request Step Config Fields:** * `type` - `"request"` (optional, defaults to request) * `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 * `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 * `pagination` - Pagination configuration (HTTP only) **Transform Step Config Fields:** * `type` - `"transform"` (required) * `transformCode` - JavaScript function: `(sourceData) => transformedData` **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" ```