> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superglue.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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;
  }
  ```

  ```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
  ```
</CodeGroup>

**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).

<CodeGroup>
  ```typescript TypeScript theme={null}
  // 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";
  }
  ```

  ```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
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```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<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;
  }
  ```

  ```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
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  interface RunRequest {
    runId?: string;
    inputs?: Record<string, any>;
    credentials?: Record<string, string>;
    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
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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()`.

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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()`.

<CodeGroup>
  ```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
  ```
</CodeGroup>

**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

<CodeGroup>
  ```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"
  ```
</CodeGroup>

***

### ToolStepMethod

<CodeGroup>
  ```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"
  ```
</CodeGroup>

***

### ToolStepFailureBehavior

<CodeGroup>
  ```typescript TypeScript theme={null}
  type ToolStepFailureBehavior = "fail" | "continue";
  ```

  ```python Python theme={null}
  from enum import Enum

  class ToolStepFailureBehavior(str, Enum):
      FAIL = "fail"
      CONTINUE = "continue"
  ```
</CodeGroup>