SDK

The @swirls/sdk package provides a type-safe TypeScript client for the Swirls API.

Installation

npm install @swirls/sdk

Client

Import Swirls from @swirls/sdk/client and construct it with a Swirls bearer credential:

import { Swirls } from '@swirls/sdk/client'

const swirls = new Swirls({
  apiKey: 'your-swirls-bearer-token',
  apiUrl: 'https://swirls.ai/api', // optional, defaults to this value
})

const projects = await swirls.client.projects.listProjects()

The constructor accepts:

The Swirls instance exposes two properties:

• swirls.client: The typed oRPC client. Use swirls.client.<namespace>.<method>(input) to call any endpoint.
• swirls.query: TanStack Query utilities for React applications.

Transport: all calls go to {apiUrl}/rpc with Authorization: Bearer <token>.

Federated authentication

For OIDC federation, pass a token source from @swirls/sdk/auth instead of a static session credential. It exchanges a JWT carrying the audience of one registered project for a short-lived credential confined to that project and refreshes it before expiry. Fabric selects the project from verified issuer/audience claims, not a projectId exchange parameter.

import { Swirls } from '@swirls/sdk/client'
import { createFederatedTokenSource } from '@swirls/sdk/auth'

const swirls = new Swirls({
  apiKey: createFederatedTokenSource({
    getSubjectToken: () => mintIdpJwtForProjectUser(),
  }),
})

Create one token source per subject and project registration. Reusing a source across users or projects can reuse the wrong cached credential. Project parameters on API calls cannot expand token scope. Federation supports authorized workload APIs, including chat streaming and execution-event subscriptions. Provider administration and deployment require a management credential. See OIDC Federation for supported operations and setup.

Namespaces

See the Client page for all namespaces.

• Decisions: (4 methods)
• Studio: Manage Studio sessions and inspect project workspaces. (7 methods)
• Agents: Create and manage agent chat sessions, and list the agents in a deployment. (18 methods)
• Workflows: Inspect deployed workflows, start executions, and read run state and traces. (8 methods)
• Deployments: Deploy and inspect project deployments. (7 methods)
• Forms: Read deployed form definitions and submissions. (3 methods)
• Webhooks: Read deployed webhook definitions and snapshots. (2 methods)
• Schedules: Read deployed schedules and their snapshots. (2 methods)
• Playbooks: Create, inspect, and update hosted test runs. (4 methods)
• Reviews: Human-in-the-loop reviews that pause workflow execution until approved or rejected. (4 methods)
• Organizations: Read project counts for your organizations. (1 method)
• Projects: Manage projects and project settings. (16 methods)
• Project Networks: Inspect network requirements, configure shared transport, and suspend connectivity. (4 methods)
• Billing: Usage, credits, and billing hold information. (4 methods)
• Costs: Read project credit usage over a time range. (1 method)
• Integrations: Link GitHub repositories and manage provider connections. (15 methods)
• MCP servers: Bind, test, and authenticate remote MCP servers for agents. (7 methods)
• Connectors: Manage inbound MCP connectors and client credentials. (7 methods)
• Identity Federation: Configure project-scoped OIDC federation, reusable organization providers, and explicit inheritance. (4 methods)
• Member attributes: Assign project attributes used by access roles. (3 methods)
• Secrets: Manage secrets for projects and integrations. (5 methods)
• Streams: Stream resources and related APIs. (4 methods)
• Views: Inspect view schemas, query materialized rows, and start backfills. (4 methods)
• Queries: Run declared read-only database queries. (1 method)
• Apps: Read hosted apps and manage their audiences, conversations, and realtime grants. (35 methods)
• Managed databases: Inspect managed databases, work with rows, and manage connections and migrations. (13 methods)
• External Postgres: Inspect declared external Postgres tables and read or modify rows. (5 methods)
• Disks: List directories and read files on shared disks. (7 methods)
• File values: Authorize uploads, complete file objects, and request previews. (4 methods)
• Audit: Audit log and compliance queries. (4 methods)
• Traces: Find execution traces and read their spans. (11 methods)