Skip to content
Helmdesk
DocsBlogPricingProductSupport
Sign inGet started

Quickstart

Get up and running with the Helmdesk SDK in under 2 minutes.

1. Install the SDK

npm install @helmdesk/sdk

2. Create a client

Create a key from Admin Settings → API keys — limited to this project, since it lives inside the app — and initialize the client:

import { HelmdeskClient } from '@helmdesk/sdk'

const helmdesk = new HelmdeskClient({
  apiKey: process.env.HELMDESK_API_KEY!,
  // project: 'ledgerly', // only for a key that reaches several projects — see below
})

Which project?

Every request belongs to one project. A key limited to one project implies it — send nothing extra. A key that reaches several projects (the kind you give a coding agent) names the project on each request with the Helmdesk-Project header (slug or id) or ?project=; without it the API answers 400 project.required with the projects it could have meant. Every object in a response carries projectId and projectSlug, so you can always tell what you are looking at.

curl
curl https://helmdesk.dev/api/v1/tickets \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"
SDK
// Pin the project once — or set HELMDESK_PROJECT and omit it.
const helmdesk = new HelmdeskClient({ apiKey, project: 'ledgerly' })
await helmdesk.tickets.list()

See Authentication for how keys and projects fit together.

3. Create your first ticket

const ticket = await helmdesk.tickets.create({
  subject: 'Cannot login',
  body: 'I keep getting a 403 error when trying to sign in.',
  customerEmail: 'user@example.com',
  customerName: 'Jane Smith',
  priority: 'high',
})

console.log(ticket.number) // e.g. 42

4. Send an email

After configuring an email provider and creating a template in the dashboard:

await helmdesk.emails.send({
  templateKey: 'welcome',
  to: { email: 'user@example.com', name: 'Jane' },
  variables: { activationUrl: 'https://myapp.com/activate/abc' },
})

Next steps