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 your API key:

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

const swirls = new Swirls({
  apiKey: 'your-api-key',
  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 API key. It exchanges a JWT from your identity provider for a short-lived Swirls token and refreshes it automatically.

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

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

See OIDC Federation for provider setup, and the Embed agent chat guide for an end-to-end example.

Namespaces

See the Client page for all namespaces.

• Agents: Create and manage agent chat sessions, and list the agents in a deployment. (8 methods)
• Workflows: Create, update, execute, and manage workflows, nodes, and edges. (5 methods)
• Deployments: Deploy and inspect project deployments. (7 methods)
• Forms: Create and manage forms that can trigger workflow executions. (3 methods)
• Webhooks: Create and manage webhook endpoints that can trigger workflow executions. (2 methods)
• Schedules: Create and manage cron schedules that can trigger workflow executions. (2 methods)
• Reviews: Human-in-the-loop reviews that pause workflow execution until approved or rejected. (4 methods)
• Projects: Manage projects and project settings. (11 methods)
• Billing: Usage, credits, and billing hold information. (3 methods)
• Identity Federation: Register and manage external identity providers for OIDC federation. (3 methods)
• Secrets: Manage secrets for projects and integrations. (5 methods)
• Streams: Stream resources and related APIs. (2 methods)
• Audit: Audit log and compliance queries. (2 methods)