SDK Reference

The SDK is in early alpha — it is not meant for production use and may be removed in the future. Stay on the latest version (@superset_sh/sdk@latest) while we iterate.

Client

import Superset from '@superset_sh/sdk';

const client = new Superset({
  apiKey: 'sk_live_…',
  organizationId: '…',
  // optional:
  baseURL: 'https://api.superset.sh',
  relayURL: 'https://relay.superset.sh',
  timeout: 60_000,
  maxRetries: 2,
  logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug'
});

tasks

`tasks.list(params?)`

List tasks with rich filters. All filters AND-combine.

const tasks = await client.tasks.list({
  assigneeMe: true,          // tasks assigned to you
  creatorMe: true,           // tasks you created
  priority: 'high',
  statusId: '<uuid>',
  assigneeId: '<uuid>',      // someone else's tasks
  search: 'auth',            // substring of title
  limit: 50,                 // max 500
  offset: 0,
});

Returns Array<TaskListItem> — each row is a Task denormalized with assigneeName, assigneeImage, creatorName, creatorImage, and statusName so you don't need follow-up calls for display.

`tasks.delete(id)`

Soft-delete a task.

await client.tasks.delete(id);

workspaces

`workspaces.create({ hostId, projectId, name, branch, agents? })`

Create a worktree on a specific host. Optionally spawn one or more agents inside it as soon as the worktree is ready. Goes through the relay tunnel — the host must be online.

Each entry in agents takes a preset id (e.g. "claude") or a HostAgentConfig instance UUID — the host service resolves it against its configured rows and copies their stored command, args, and env. Use agents.list({ hostId }) to enumerate what's installed.

const ws = await client.workspaces.create({
  hostId: '<machineId>',     // see hosts.list()
  projectId: '<uuid>',       // see projects.list()
  name: 'wire-up-auth',
  branch: 'feat/auth',
  agents: [                  // optional — spawn agents on creation
    { agent: 'claude', prompt: 'Implement the auth flow described in SUPER-100.' },
    { agent: 'claude', prompt: 'Write integration tests for the new auth flow.' },
  ],
});

console.log(ws.id, ws.agentRuns.map((r) => r.runId));

Returns a CreatedWorkspace — a HostWorkspace plus an agentRuns array (one entry per agent in the request, empty if agents was omitted).

`workspaces.delete(id, opts?)`

Delete a workspace. Looks up its host automatically and routes through the relay.

await client.workspaces.delete(id);
// or skip the lookup:
await client.workspaces.delete(id, { hostId: '<machineId>' });

projects

`projects.list()`

Returns Array<Project>.

const projects = await client.projects.list();

hosts

`hosts.list()`

List developer machines registered in the org. Returns Array<Host> with id (machineId), name, online, and organizationId.

const hosts = await client.hosts.list();
const online = hosts.filter((h) => h.online);

agents

Terminal-agent rows configured on a specific host (the same rows shown in Settings → Agents on that machine). Reads route through the relay tunnel — the target host must be online.

`agents.list({ hostId })`

List configured agents on a host in persisted display order. First call on a fresh host seeds the bundled defaults. Returns Array<HostAgentConfig> — each row carries id, presetId, label, command, args, env, and prompt-transport fields used to launch the agent.

const agents = await client.agents.list({ hostId: '<machineId>' });

`agents.run({ workspaceId, agent, prompt, attachmentIds? }, { hostId? })`

Launch an agent inside an existing workspace. By default looks up the host that owns the workspace via the cloud index; pass an explicit hostId to skip the lookup.

agent accepts either a preset id (e.g. "claude") or a HostAgentConfig instance UUID. Returns { sessionId, label }.

const { sessionId } = await client.agents.run({
  workspaceId: '<uuid>',
  agent: 'claude',
  prompt: 'Audit the login flow for race conditions.',
});

automations

Recurring agent runs scheduled by RRULE. Requires a Pro subscription on the org for create / update / delete.

`automations.list()`

const automations = await client.automations.list();

Each row is an AutomationSummary — the prompt body is omitted (it can be large markdown). Fetch one with automations.getPrompt(id). Each row includes scheduleText, a human-readable rendering of the rrule.

`automations.retrieve(id)`

const a = await client.automations.retrieve(id);

Returns an AutomationSummary (no prompt body — call getPrompt(id)).

`automations.create(body)`

Create a recurring automation.

const a = await client.automations.create({
  name: 'Daily leads',
  prompt: 'Find new leads from Linear and update the CRM…',
  agent: 'claude', // host agent presetId, instance UUID, or 'superset' for built-in chat
  rrule: 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0',
  timezone: 'America/Los_Angeles',
  v2ProjectId: '<uuid>',     // one of v2ProjectId or v2WorkspaceId required
  // optional:
  v2WorkspaceId: '<uuid>',   // pin to a specific workspace
  targetHostId: '<machineId>', // pin to a specific host
  dtstart: new Date().toISOString(),
  mcpScope: ['linear', 'notion'],
});

`automations.update(body)`

await client.automations.update({ id, rrule: 'FREQ=WEEKLY;BYDAY=MO' });

`automations.delete(id)`

`automations.run(id)`

Dispatch immediately, off-schedule. Goes through the relay to the pinned host.

const run = await client.automations.run(id);
console.log(run.status, run.hostId);

`automations.pause(id)` / `automations.resume(id)`

Toggle the enabled flag. A paused automation stops running on its schedule until you resume it.

`automations.logs(id, params?)`

Run history. Owner-only — returns 404 if the automation isn't owned by the calling user.

const runs = await client.automations.logs(id, { limit: 20 });

`automations.getPrompt(id)` / `automations.setPrompt(id, prompt)`

Read or replace the automation's prompt without going through the full update.