integration.md7.1 KBView on GitHub # Integrating superglue into Your Codebase
After building and saving tools with the CLI, integrate them into your application.
## Quick Reference: REST API (curl)
For any language, use the REST API directly:
```bash
# Set your API key and endpoint
export SUPERGLUE_API_KEY=[redacted]
export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud"
# Run a tool (sync - waits for completion)
curl -X POST "$SUPERGLUE_API_ENDPOINT/v1/tools/my-tool-id/run" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": {"userId": "123"}}'
# Run a tool (async - returns immediately)
curl -X POST "$SUPERGLUE_API_ENDPOINT/v1/tools/my-tool-id/run" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": {"userId": "123"}, "options": {"async": true}}'
# Get run status/result
curl "$SUPERGLUE_API_ENDPOINT/v1/runs/{runId}" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY"
# List tools
curl "$SUPERGLUE_API_ENDPOINT/v1/tools?page=1&limit=50" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY"
# Get tool details
curl "$SUPERGLUE_API_ENDPOINT/v1/tools/my-tool-id" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY"
# Cancel a running tool
curl -X POST "$SUPERGLUE_API_ENDPOINT/v1/runs/{runId}/cancel" \
-H "Authorization: Bearer $SUPERGLUE_API_KEY"
```
### Response Format
**Sync execution (200 OK):**
```json
{
"runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
"toolId": "my-tool-id",
"status": "success",
"data": { "result": "..." },
"stepResults": [{ "stepId": "step-1", "success": true, "data": {} }],
"metadata": {
"startedAt": "2024-01-15T10:00:00Z",
"completedAt": "2024-01-15T10:00:05Z",
"durationMs": 5234
}
}
```
**Async execution (202 Accepted):**
```json
{
"runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
"toolId": "my-tool-id",
"status": "running"
}
```
---
## SDK Installation
**Always install the latest version** — older SDK versions may have known bugs (e.g. case-sensitivity issues on Linux in versions before 3.3.0).
```bash
# TypeScript/JavaScript
npm install @superglue/client@latest
# Python
pip install --upgrade superglue-client
```
Both SDKs are auto-generated from the OpenAPI spec (JS via orval, Python via openapi-python-client).
## TypeScript/JavaScript Usage
The JS SDK exports: `configure`, `listTools`, `getTool`, `runTool`, `getRun`, `cancelRun`, `triggerWebhook`, `listRuns`.
```typescript
import { configure, runTool, getRun, listTools, getTool } from "@superglue/client";
configure({
apiKey=[redacted],
baseUrl: "https://api.superglue.cloud/v1",
});
```
### Run a Tool (Sync)
```typescript
const response = await runTool("my-tool-id", {
inputs: { userId: "123", date: "2024-01-15" },
});
if (response.status === 200) {
const run = response.data;
console.log(run.status); // "success" | "failed"
console.log(run.data); // tool output
} else {
console.error("Error:", response.data);
}
```
The response is `{ data: Run, status: number, headers: Headers }`. The `Run` object has: `runId`, `toolId`, `status`, `data`, `error`, `stepResults`, `metadata`.
### Async Execution (Fire-and-Forget)
```typescript
const response = await runTool("my-tool-id", {
inputs: { userId: "123" },
options: { async: true },
});
if (response.status === 202) {
const run = response.data;
console.log(`Run started: ${run.runId}`);
let latest = run;
while (latest.status === "running") {
await new Promise((r) => setTimeout(r, 1000));
const poll = await getRun(latest.runId);
latest = poll.data;
}
}
```
### List and Discover Tools
```typescript
const { data: tools } = await listTools({ page: 1, limit: 50 });
console.log(tools.data);
const { data: tool } = await getTool("my-tool-id");
console.log(tool.inputSchema);
```
## Python Usage
The Python SDK uses `AuthenticatedClient` with httpx. Functions are in `superglue_client.api.tools` and `superglue_client.api.runs`.
```python
import os
from superglue_client import AuthenticatedClient
from superglue_client.api.tools import run_tool, list_tools, get_tool
from superglue_client.api.runs import get_run
from superglue_client.models.run_request import RunRequest
from superglue_client.models.run_request_inputs import RunRequestInputs
client = AuthenticatedClient(
base_url="https://api.superglue.cloud/v1",
token=[redacted]SUPERGLUE_API_KEY"],
)
```
### Run a Tool (Sync)
```python
with client as c:
result = run_tool.sync(
"my-tool-id",
client=c,
body=RunRequest(
inputs=RunRequestInputs.from_dict({"userId": "123"}),
),
)
if hasattr(result, "status") and result.status == "success":
print(result.data)
elif hasattr(result, "error"):
print(result.error)
```
`sync()` returns `Run | Error | None`. Use `sync_detailed()` for the full `Response` wrapper with status code and headers.
### Async Python
```python
async with client as c:
result = await run_tool.asyncio(
"my-tool-id",
client=c,
body=RunRequest(
inputs=RunRequestInputs.from_dict({"userId": "123"}),
),
)
```
## Webhook Triggers
Trigger tools via HTTP POST without SDK. Webhooks execute asynchronously.
```bash
curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=[redacted] \
-H "Content-Type: application/json" \
-d '{"userId": "123"}'
```
### Webhook URL Pattern
```
POST {endpoint}/v1/hooks/{toolId}?token=[redacted]
```
- `endpoint` — Your superglue API endpoint
- `toolId` — The saved tool ID (from `sg tool save`)
- `apiKey` — Your superglue API key (passed as `token` query param)
### Webhook Response
Webhooks return `202 Accepted` immediately:
```json
{
"runId": "uuid-of-execution",
"status": "accepted",
"toolId": "my-tool-id"
}
```
To get the result, poll the run status:
```bash
curl "https://api.superglue.cloud/v1/runs/{runId}" \
-H "Authorization: Bearer {apiKey}"
```
## Error Handling
### Retry Pattern (TypeScript)
```typescript
async function runToolWithRetry(toolId: string, inputs: Record<string, any>, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
const response = await runTool(toolId, { inputs });
if (response.status === 200 && response.data.status === "success") {
return response.data;
}
if (response.data.error?.includes("validation")) {
throw new Error(response.data.error);
}
if (attempt < maxRetries) {
await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
}
}
throw new Error(`Tool ${toolId} failed after ${maxRetries} attempts`);
}
```
## Environment Configuration
```bash
# Required
SUPERGLUE_API_KEY=[redacted]
# Optional (defaults to hosted)
SUPERGLUE_API_ENDPOINT=https://api.superglue.cloud
```
## Best Practices
1. **Store API keys in secrets** — Never commit to version control
2. **Validate payloads client-side** — Check against `inputSchema` before calling
3. **Handle errors gracefully** — Tools can fail due to external API issues
4. **Monitor run history** — Use `sg run list` or the web UI to track executions
5. **Use async mode for long-running tools** — Avoid timeouts on complex workflows