REST API

The setup view of one project, by slug or id: branding, the public support and knowledge-base URLs, whether email sending is configured (the from address, mode and provider name — never credentials), and the widget install snippet. The first call after creating a project. Resolved among the projects the key can reach; anything else is 403 project.forbidden.

Request

curl https://helmdesk.dev/api/v1/projects/ledgerly \
  -H "Authorization: Bearer sk_live_..."

// SDK
const project = await helmdesk.projects.get('ledgerly')

Response

{
  "id": "5c1e7d0a-…", "slug": "ledgerly", "name": "Ledgerly",
  "branding": { "brandName": "Ledgerly", "logoUrl": "…", "iconUrl": null, "primaryColor": "#6366f1", "websiteUrl": "…" },
  "urls": { "support": "https://helmdesk.dev/p/ledgerly/support", "articles": "https://helmdesk.dev/p/ledgerly/articles" },
  "email": { "configured": true, "fromEmail": "hello@ledgerly.app", "fromName": "Ledgerly", "sendingMode": "live", "provider": "resend", "supportEmail": "…" },
  "widget": { "installSnippet": "<script src=\"https://helmdesk.dev/widget.js\" data-project=\"ledgerly\"></script>" }
}

widget.identitySecret — the HMAC secret for identified widget users — is included only when the key holds projects:manage, and it is the secret for the request's environment (live or sandbox).

One snapshot of how the project is doing, for the request's environment: the ticket queue by status plus how many await a reply and how many of those are stale (5+ days), tickets resolved this week, open error issues and log volume in the last 24 hours, email delivery this week, feedback over 30 days, and agent actions awaiting review. Ticket definitions are the dashboard's own, so the numbers match what it shows.

Request

curl https://helmdesk.dev/api/v1/overview \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"

// SDK — the client's project and environment
const overview = await helmdesk.projects.overview()

Response

{
  "projectId": "5c1e7d0a-…", "projectSlug": "ledgerly", "environment": "live",
  "tickets": { "new": 3, "open": 7, "pending": 2, "awaitingReply": 5, "resolvedLast7d": 14, "staleAwaitingReply": 1 },
  "logs": { "openErrorIssues": 2, "eventsLast24h": 418 },
  "emails": { "sentLast7d": 1250, "failedLast7d": 4, "blockedLast7d": 1, "scheduled": 12 },
  "feedback": { "openConversations": 3, "responsesLast30d": 21, "averageRating30d": 4.3 },
  "agents": { "pendingReview": 2 },
  "generatedAt": "2026-09-09T11:10:00.000Z"
}

Where the account stands against its plan — the answer to “why did I hit a cap?”. Every meter is reported next to its limit; -1 means unlimited, the same convention as the plan table. Monthly meters (tickets, emails, logs, agent runs) reset on the 1st of the UTC month given in period. Account-scoped: no project is needed.

Request

curl https://helmdesk.dev/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."

// SDK
const usage = await helmdesk.account.usage()

Response

{
  "plan": { "tier": "starter", "status": "active" },
  "period": { "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z" },
  "tickets": { "used": 412, "allowance": 1000, "overage": false },
  "emails": { "used": 9800, "limit": 25000 },
  "logs": { "used": 61200, "limit": 100000, "retentionDays": 7 },
  "storage": { "usedBytes": 184549376, "limitBytes": 5368709120 },
  "agentRuns": { "used": 120, "limit": 500 },
  "projects": { "count": 2, "limit": 3 },
  "teamMembers": { "count": 3, "limit": -1 }
}

tickets.overage: truemeans the month's allowance is used up: paid tiers keep accepting tickets and bill the excess, Free pauses intake (the public form answers with a 503 until the month resets).