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

interface Tool {
  id: string;
  name?: string;
  version?: string;
  instruction?: string;
  inputSchema?: Record<string, any>;
  outputSchema?: Record<string, any>;
  steps: ToolStep[];
  outputTransform?: string;
  createdAt?: string;
  updatedAt?: string;
}

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

// Request step (API calls)
interface RequestStepConfig {
  type?: "request";
  url: string;
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  systemId: string;
  queryParams?: Record<string, string>;
  headers?: Record<string, string>;
  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";
}

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:

{
  "query": "<<(sourceData) => sourceData.step1.userId>>",
  "limit": "<<(sourceData) => sourceData.inputs.limit>>"
}

---

Run types

Run

Represents a tool execution with status, results, and metadata.

TypeScript

interface Run {
  runId: string;
  toolId: string;
  status: "running" | "success" | "failed" | "aborted";
  tool?: {
    id: string;
    name?: string;
    version?: string;
  };
  toolPayload?: {
    inputs?: Record<string, any>;
    credentials?: Record<string, string>;
    options?: Record<string, any>;
  };
  data?: any;
  error?: string;
  stepResults?: RunStepResultsItem[];
  options?: Record<string, any>;
  requestSource?: string;
  traceId?: string;
  metadata: RunMetadata;
}

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

interface RunMetadata {
  startedAt?: string;
  completedAt?: string;
  durationMs?: number;
}

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

interface RunRequest {
  runId?: string;
  inputs?: Record<string, any>;
  credentials?: Record<string, string>;
  options?: {
    async?: boolean;
    timeout?: number;
    webhookUrl?: string;
    traceId?: string;
  };
}

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

interface RunStepResultsItem {
  stepId: string;
  success: boolean;
  data?: any;
  error?: string;
}

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

interface Pagination {
  type: "offset" | "cursor";
  pageSize?: string;
  cursorPath?: string;
  stopCondition?: string;
}

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, sourceData) => boolean
  • response - Object with {data: ..., headers: ...}
  • pageInfo - Object with {page, offset, cursor, totalFetched, mergedResult}
  • pageInfo.totalFetched - Count from the merged paginated result, including the current page
  • pageInfo.mergedResult - Accumulated paginated result including the current page
  • sourceData - Current step input data with payload fields at the root plus previous step results
  • Return true to STOP, false to continue

---

Response types

ListTools200

Response from listTools().

TypeScript

interface ListTools200 {
  data?: Tool[];
  page?: number;
  limit?: number;
  total?: number;
  hasMore?: boolean;
}

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

interface ListRuns200 {
  data?: Run[];
  page?: number;
  limit?: number;
  total?: number;
  hasMore?: boolean;
}

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

type RunStatus = "running" | "success" | "failed" | "aborted";

---

ToolStepMethod

TypeScript

type ToolStepMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

---

ToolStepFailureBehavior

TypeScript

type ToolStepFailureBehavior = "fail" | "continue";