JavaScript SDK

The @swarmhit/swarmhit-sdk package is the official client for the Swarmhit API in JavaScript and TypeScript. It covers every endpoint and handles the parts every integration would otherwise write itself:

• Typed end to end: every parameter, result and webhook event has a TypeScript type, and your editor shows each method's documentation.
• Safe retries: the SDK retries network errors, timeouts and server errors. One-off sends (messages, InMails, invitations, emails) carry an idempotency key, so a retry never sends twice, and nothing else that creates is retried blindly.
• Pagination: iterate a list with for await and the SDK fetches the next pages as you go.
• Webhook verification: one call checks a delivery's signature and gives you a typed event.
• No dependencies: it runs on Node 20+, Bun, Deno, Cloudflare Workers and Vercel Edge.

Install

npm install @swarmhit/swarmhit-sdk

Your first call

Create an API key on the Access tokens page in Swarmhit. Keys start with swh_live_. Put the key in the SWARMHIT_API_KEY environment variable, where the SDK reads it:

import Swarmhit from '@swarmhit/swarmhit-sdk';

const swarmhit = new Swarmhit(); // reads SWARMHIT_API_KEY

const info = await swarmhit.info();
console.log(`Connected to ${info.workspace.name} (${info.workspace.plan})`);

SWARMHIT_API_KEY=swh_live_xxxxxxxx node hello.mjs

An API key gives full access to its workspace, so keep it on your server: see Browsers and apps.

A complete example

Create a campaign, add two leads, start it and follow its progress. The example needs at least one LinkedIn sender connected to your workspace (see Sender accounts):

import Swarmhit from '@swarmhit/swarmhit-sdk';

const swarmhit = new Swarmhit();

// The LinkedIn sender that will run the campaign.
const { data: senders } = await swarmhit.accounts.list();

const campaign = await swarmhit.campaigns.create({
  name: 'Q4 founders',
  linkedinAccountIds: [senders[0].id],
  sequence: {
    steps: [
      { type: 'invite', config: { note: 'Hi {{firstName}}, glad to connect!', fallbackNote: 'Hi, glad to connect!' } },
      { type: 'message', config: { text: 'Thanks for connecting, {{firstName}}!', fallbackText: 'Thanks for connecting!' } },
    ],
  },
});

await swarmhit.campaigns.leads.add(campaign.id, {
  leads: [
    { profileUrl: 'https://www.linkedin.com/in/ada-lovelace', firstName: 'Ada' },
    { profileUrl: 'https://www.linkedin.com/in/grace-hopper', firstName: 'Grace' },
  ],
});

await swarmhit.campaigns.update(campaign.id, { status: 'active' });

for await (const lead of swarmhit.campaigns.leads.list(campaign.id)) {
  console.log(lead.leadId, lead.status);
}

A message that uses a {{variable}} needs a fallback (fallbackNote, fallbackText), which is sent to leads with no value for that variable. A campaign without its fallbacks cannot be activated.

Every method follows the same pattern: ids first, then one object with the parameters. It resolves to the object the API returns. A list method resolves to a page, with the items in data. The Recipes page has more end-to-end examples.

Next steps