@happyrobot-ai/sdk
TypeScript SDK for the HappyRobot Public API.
Installation
npm install @happyrobot-ai/sdk
# or
pnpm add @happyrobot-ai/sdk
# or
yarn add @happyrobot-ai/sdk
Optional: If you plan to use HappyRobotVoiceClient (imported from @happyrobot-ai/sdk/voice) for browser-side voice calls, also install livekit-client:
npm install livekit-client
# or
pnpm add livekit-client
# or
yarn add livekit-client
This is only needed for voice — all other SDK features work without it.
Quick Start
import { HappyRobotClient } from "@happyrobot-ai/sdk";
const client = new HappyRobotClient({ apiKey: "sk_live_..." });
// List workflows
const { data } = await client.workflows.list();
// Trigger a run
const { run_id } = await client.workflows.triggerRun("my-workflow", {
payload: { phone: "+1234567890" },
});
Configuration
const client = new HappyRobotClient({
apiKey: "sk_live_...", // Required. API key (sk_live_... or sk_test_...)
cluster: "eu", // Optional. "us" (default) or "eu"
timeout: 30_000, // Optional. Request timeout in ms. Defaults to 30000
maxRetries: 2, // Optional. Retries on 429/5xx with exponential backoff. Defaults to 2
fetch: customFetch, // Optional. Custom fetch implementation
});
Helpers
High-level convenience functions available via @happyrobot-ai/sdk/helpers.
triggerAndWait
Trigger a workflow run and poll until it reaches a terminal status.
import { triggerAndWait } from "@happyrobot-ai/sdk/helpers";
const { run, sessions } = await triggerAndWait(client, {
workflowId: "my-workflow",
payload: { phone: "+1234567890" },
timeoutMs: 300_000, // Optional. Defaults to 5 minutes
pollIntervalMs: 2_000, // Optional. Defaults to 2 seconds
fetchSessions: true, // Optional. Fetch sessions on completion. Defaults to true
environment: "production", // Optional. Defaults to "production"
});
console.log(run.status); // "completed" | "failed" | "canceled" | ...
createVoiceAgent
Create a voice agent workflow from a template with optional publishing.
import { createVoiceAgent } from "@happyrobot-ai/sdk/helpers";
const { workflow, publishResult } = await createVoiceAgent(client, {
name: "Sales Agent",
template: "voice-agent", // "voice-agent" (outbound) or "inbound-voice-agent"
prompt: "You are a helpful sales assistant...",
initialMessage: "Hi, how can I help you today?",
publish: true,
environment: "production",
folderId: "folder-id", // Optional
});
createFromTemplate
Create any workflow from a template with custom inputs.
import { createFromTemplate } from "@happyrobot-ai/sdk/helpers";
const { workflow } = await createFromTemplate(client, {
template: "voice-agent",
name: "My Agent",
inputs: { agent_name: "My Agent" },
publish: false,
});
Resources
| Property | Class | Description |
|---|---|---|
client.workflows | WorkflowsResource | Workflow CRUD, publishing, runs, and templates |
client.versions | VersionsResource | Version management (fork, publish, lock, test) |
client.nodes | NodesResource | Node CRUD, config schema, and available variables |
client.runs | RunsResource | Run details, cancellation, and annotations |
client.sessions | SessionsResource | Session details, messages, and SSE streaming |
client.messages | MessagesResource | Message quality flags |
client.variables | VariablesResource | Workflow-scoped variables |
client.phoneNumbers | PhoneNumbersResource | Phone number management |
client.sipTrunks | SipTrunksResource | SIP trunk management |
client.integrations | IntegrationsResource | Integration and event discovery |
client.contacts | ContactsResource | Contact lookup and history |
client.knowledgeBases | KnowledgeBasesResource | Knowledge base document management |
client.workflowFolders | WorkflowFoldersResource | Workflow folder organization |
client.mcp | MCPResource | MCP server management |
client.billing | BillingResource | Billing usage details and totals |
client.apiKey | ApiKeyResource | API key introspection |
client.artifacts | ArtifactsResource | Resolve authorized artifact download URLs |
client.adversarialSuites | AdversarialSuitesResource | Retained adversarial suite history |
client.adversarialTests | AdversarialTestsResource | Retained adversarial test history |
client.northstars | NorthstarsResource | Northstar quality criteria management |
client.customEvals | CustomEvalsResource | Custom eval management and execution |
client.nodeTests | NodeTestsResource | Saved node tests and run history |
client.issues | IssuesResource | Quality issue (flag) status management |
client.auditRemarks | AuditRemarksResource | Audit remark feedback management |
client.chat | ChatResource | Chat session management, messaging, and file uploads |
client.voice | VoiceResource | Voice catalog lookup and call token creation |
client.workflows
// List workflows (paginated)
const { data, pagination } = await client.workflows.list({ page: 1, limit: 20 });
// Iterate all workflows across pages
for await (const wf of client.workflows.listAll()) { ... }
// Create a workflow
const wf = await client.workflows.create({ name: "My Workflow" });
// Get by ID or slug
const wf = await client.workflows.get("my-workflow");
// Update
await client.workflows.update("my-workflow", { name: "New Name" });
// Delete
await client.workflows.delete("my-workflow");
// Duplicate
await client.workflows.duplicate("my-workflow", { name: "Copy" });
// Publish / unpublish
await client.workflows.publish("my-workflow");
await client.workflows.unpublish("my-workflow");
// Cancel current and queued runs. By default, this also unpublishes the workflow.
await client.workflows.cancelRuns("my-workflow");
await client.workflows.cancelRuns("my-workflow", { unpublish_workflow: false });
// List templates
const { data } = await client.workflows.listTemplates();
// List versions
const { data } = await client.workflows.listVersions("my-workflow");
// List runs
const { data } = await client.workflows.listRuns("my-workflow");
// List sessions across all runs
const { data: sessions } = await client.workflows.listSessions("my-workflow");
// Trigger a run
const { run_id } = await client.workflows.triggerRun("my-workflow", { payload: { phone: "+1..." } });
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /workflows | List workflows, paginated |
listAll(query?) | GET | /workflows | Async generator over all pages |
create(body) | POST | /workflows | Create a new workflow |
get(workflowId) | GET | /workflows/:id | Get workflow by ID or slug |
update(workflowId, body) | PATCH | /workflows/:id | Update name, description, etc. |
delete(workflowId) | DELETE | /workflows/:id | Delete a workflow |
duplicate(workflowId, body?) | POST | /workflows/:id/duplicate | Duplicate a workflow |
publish(workflowId, body?) | POST | /workflows/:id/publish | Publish the latest version |
unpublish(workflowId) | POST | /workflows/:id/unpublish | Unpublish a workflow |
cancelRuns(workflowId, body?) | POST | /workflows/:id/cancel-runs | Cancel current and queued runs |
listTemplates(query?) | GET | /workflows/templates | List workflow templates |
listVersions(workflowId, query?) | GET | /workflows/:id/versions | List versions for a workflow |
listRuns(workflowId, query?) | GET | /workflows/:id/runs | List runs for a workflow |
listSessions(workflowId, query?) | GET | /workflows/:id/sessions | List sessions for a workflow |
triggerRun(workflowId, body?) | POST | /workflows/:id/runs | Trigger a new run |
client.versions
const version = await client.versions.get("version-id");
await client.versions.update("version-id", { name: "v2" });
await client.versions.fork("version-id");
await client.versions.publish("version-id");
await client.versions.unpublish("version-id");
await client.versions.lock("version-id");
await client.versions.unlock("version-id");
await client.versions.testAll("version-id");
const issues = await client.versions.getPromptIssues("version-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
get(versionId) | GET | /versions/:id | Get version with node summary and changelog |
update(versionId, body) | PATCH | /versions/:id | Update name or description |
fork(versionId) | POST | /versions/:id/fork | Clone a version |
publish(versionId, body?) | POST | /versions/:id/publish | Publish a version |
unpublish(versionId) | POST | /versions/:id/unpublish | Unpublish a version |
lock(versionId) | POST | /versions/:id/lock | Lock a version (prevent edits) |
unlock(versionId) | POST | /versions/:id/unlock | Unlock a version |
testAll(versionId) | POST | /versions/:id/test-all | Run test-all validation |
getPromptIssues(versionId) | GET | /versions/:id/prompt-issues | Get prompt quality issues for all prompt nodes |
client.nodes
Nodes are always scoped to a version.
const nodes = await client.nodes.list("version-id");
await client.nodes.addBatch("version-id", { nodes: [...] });
const node = await client.nodes.get("version-id", "node-id");
await client.nodes.update("version-id", "node-id", { config: { ... } });
await client.nodes.delete("version-id", "node-id");
const schema = await client.nodes.getConfigSchema("version-id", "node-id");
const vars = await client.nodes.getAvailableVars("version-id", "node-id");
const result = await client.nodes.test("version-id", "node-id");
Groups returned by getAvailableVars can include is_list: true. That means variables in the group resolve as arrays outside their loop. Sequential and parallel loops both return arrays; a single iteration returns a one-item array.
| Method | HTTP | Path | Description |
|---|---|---|---|
list(versionId) | GET | /versions/:vId/nodes | List all nodes in a version |
addBatch(versionId, body) | POST | /versions/:vId/nodes | Add nodes in batch (1–50) |
get(versionId, nodeId) | GET | /versions/:vId/nodes/:nId | Get a single node |
update(versionId, nodeId, body) | PUT | /versions/:vId/nodes/:nId | Update a node |
delete(versionId, nodeId) | DELETE | /versions/:vId/nodes/:nId | Delete a node |
getConfigSchema(versionId, nodeId) | GET | /versions/:vId/nodes/:nId/config-schema | Get field types and requirements |
getAvailableVars(versionId, nodeId) | GET | /versions/:vId/nodes/:nId/available-vars | Get upstream variables available to this node |
test(versionId, nodeId, body?) | POST | /versions/:vId/nodes/:nId/test | Test a single node (version must not be published) |
client.runs
const run = await client.runs.get("run-id");
const sessions = await client.runs.getSessions("run-id");
const recordings = await client.runs.getRecordings("run-id");
const flags = await client.runs.getFlags("run-id");
await client.runs.cancel("run-id");
await client.runs.mark("run-id", { annotation: "correct" });
| Method | HTTP | Path | Description |
|---|---|---|---|
get(runId) | GET | /runs/:id | Get run details |
getSessions(runId, query?) | GET | /runs/:id/sessions | Get sessions for a run |
getRecordings(runId) | GET | /runs/:id/recordings | Get recordings for a run |
getFlags(runId, query?) | GET | /runs/:id/flags | Get quality flags for a run |
cancel(runId) | POST | /runs/:id/cancel | Cancel a run |
mark(runId, body) | POST | /runs/:id/mark | Annotate a run (correct / incorrect / critical) |
client.sessions
const session = await client.sessions.get("session-id");
const { data } = await client.sessions.getMessages("session-id");
// SSE streaming
for await (const event of await client.sessions.stream("session-id")) {
if (event.event === "message")
console.log(event.data.role, event.data.content);
if (event.event === "session_ended") break;
}
| Method | HTTP | Path | Description |
|---|---|---|---|
get(sessionId) | GET | /sessions/:id | Get session details |
getMessages(sessionId, query?) | GET | /sessions/:id/messages | Get paginated messages for a session |
stream(sessionId, query?) | GET | /sessions/:id/stream | Open SSE stream of session messages |
client.messages
const { data } = await client.messages.listFlags("message-id");
await client.messages.createFlag("message-id", {
type: "incorrect",
note: "...",
});
| Method | HTTP | Path | Description |
|---|---|---|---|
listFlags(messageId, query?) | GET | /messages/:id/flags | List quality flags for a message |
createFlag(messageId, body) | POST | /messages/:id/flags | Create a quality flag on a message |
client.artifacts
const resolved = await client.artifacts.createDownloadUrls({
artifacts: [
{
message_id: "message-id-from-the-session-messages-response",
s3_key: "artifacts/<media_id>/extracted_text.txt",
},
],
});
| Method | HTTP | Path | Description |
|---|---|---|---|
createDownloadUrls(body) | POST | /artifacts/download-urls | Resolve authorized artifact URLs with provenance |
resolve(body) | POST | /artifacts/resolve | Deprecated; sunsets October 15, 2026 at 12:00 UTC |
client.variables
Variables are scoped to a workflow.
const { data } = await client.variables.list("workflow-id");
await client.variables.create("workflow-id", {
name: "MY_VAR",
value: "hello",
});
await client.variables.update("workflow-id", "variable-id", { value: "world" });
await client.variables.delete("workflow-id", "variable-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list(workflowId, query?) | GET | /workflows/:wId/variables | List variables for a workflow |
create(workflowId, body) | POST | /workflows/:wId/variables | Create a variable |
update(workflowId, variableId, body) | PATCH | /workflows/:wId/variables/:vId | Update a variable |
delete(workflowId, variableId) | DELETE | /workflows/:wId/variables/:vId | Delete a variable |
client.phoneNumbers
const numbers = await client.phoneNumbers.list();
await client.phoneNumbers.buy({ area_code: "415" });
await client.phoneNumbers.update("id", { name: "Main Line" });
await client.phoneNumbers.getUsage("id");
await client.phoneNumbers.freeUp("id");
await client.phoneNumbers.delete("id");
await client.phoneNumbers.removeFromWorkflow("id", { use_case_id: "..." });
await client.phoneNumbers.getTollFreeVerification("id");
await client.phoneNumbers.createTollFreeVerification("id", { ... });
await client.phoneNumbers.deleteTollFreeVerification("verification-sid");
await client.phoneNumbers.createSipTrunk("id");
await client.phoneNumbers.validateTollFreeNumbers({ phone_numbers: [...] });
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /phone-numbers | List all phone numbers |
buy(body) | POST | /phone-numbers | Purchase a new phone number |
update(id, body) | PUT | /phone-numbers/:id | Update name or caller ID |
getUsage(id) | GET | /phone-numbers/:id/usage | Get usage info |
getTollFreeVerification(id) | GET | /phone-numbers/:id/tollfree-verification | Get toll-free verification status |
createTollFreeVerification(id, body) | POST | /phone-numbers/:id/tollfree-verification | Start toll-free verification |
deleteTollFreeVerification(verificationSid) | DELETE | /phone-numbers/tollfree-verification/:sid | Delete a toll-free verification |
createSipTrunk(id) | POST | /phone-numbers/:id/sip-trunk | Create a SIP trunk for a number |
freeUp(id) | POST | /phone-numbers/:id/free-up-number | Release a number from workflows |
delete(id) | POST | /phone-numbers/:id/delete-number | Permanently delete a number |
removeFromWorkflow(id, body) | POST | /phone-numbers/:id/remove-from-workflow | Remove from a specific workflow |
validateTollFreeNumbers(body) | POST | /phone-numbers/validate-toll-free-numbers | Check for conflicts |
client.sipTrunks
const trunks = await client.sipTrunks.list();
const options = await client.sipTrunks.listOptions();
await client.sipTrunks.create({ name: "Main Trunk", ... });
await client.sipTrunks.createBulk({ trunks: [...] });
const trunk = await client.sipTrunks.get("trunk-id");
await client.sipTrunks.update("trunk-id", { name: "Updated" });
await client.sipTrunks.delete("trunk-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list() | GET | /sip-trunks | List all SIP trunks |
listOptions() | GET | /sip-trunks/options | Lightweight list of trunk options |
create(body) | POST | /sip-trunks | Create a SIP trunk |
createBulk(body) | POST | /sip-trunks/bulk | Create multiple SIP trunks |
get(trunkId) | GET | /sip-trunks/:id | Get a SIP trunk |
update(trunkId, body) | PUT | /sip-trunks/:id | Update a SIP trunk |
delete(trunkId) | DELETE | /sip-trunks/:id | Delete a SIP trunk |
client.integrations
const integrations = await client.integrations.list();
const integration = await client.integrations.get("integration-id");
await client.integrations.createCredential("integration-id", { name: "My Creds", fields: { ... } });
// Integration-specific sub-resources
await client.integrations.googleSheets.spreadsheets();
await client.integrations.googleSheets.worksheets({ spreadsheet_id: "..." });
await client.integrations.googleSheets.columns({ spreadsheet_id: "...", worksheet_id: "..." });
await client.integrations.googleSheets.rows({ spreadsheet_id: "...", worksheet_id: "..." });
await client.integrations.slack.channels();
await client.integrations.slack.users();
await client.integrations.teams.teams();
await client.integrations.teams.channels();
await client.integrations.teams.users();
await client.integrations.twilioSms.phoneNumbers();
await client.integrations.whatsApp.businesses({ credential_id: "..." });
await client.integrations.whatsApp.businessAccounts({ credential_id: "...", business_id: "..." });
await client.integrations.whatsApp.phoneNumbers({ credential_id: "...", business_account_id: "..." });
await client.integrations.whatsApp.messageTemplates({ credential_id: "...", business_account_id: "..." });
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /integrations | List all integrations |
get(id) | GET | /integrations/:id | Get integration and its events |
createCredential(id, body) | POST | /integrations/:id/create-credential | Create a credential for a form-based integration |
googleSheets.spreadsheets(query?) | GET | /integrations/google-sheets/spreadsheets | List spreadsheets |
googleSheets.worksheets(query) | GET | /integrations/google-sheets/worksheets | List worksheets in a spreadsheet |
googleSheets.columns(query) | GET | /integrations/google-sheets/columns | List columns in a worksheet |
googleSheets.rows(query) | GET | /integrations/google-sheets/rows | List rows in a worksheet |
slack.channels(query?) | GET | /integrations/slack/channels | List Slack channels |
slack.users(query?) | GET | /integrations/slack/users | List Slack users |
teams.teams(query?) | GET | /integrations/teams/teams | List Microsoft Teams teams |
teams.channels(query?) | GET | /integrations/teams/channels | List Microsoft Teams channels |
teams.users(query?) | GET | /integrations/teams/users | List Microsoft Teams users |
twilioSms.phoneNumbers(query?) | GET | /integrations/twilio-sms/phone-numbers | List Twilio SMS numbers |
whatsApp.businesses(query) | GET | /integrations/whatsapp/businesses | List WhatsApp businesses |
whatsApp.businessAccounts(query) | GET | /integrations/whatsapp/business-accounts | List WhatsApp business accounts |
whatsApp.phoneNumbers(query) | GET | /integrations/whatsapp/phone-numbers | List WhatsApp phone numbers |
whatsApp.messageTemplates(query) | GET | /integrations/whatsapp/message-templates | List WhatsApp message templates |
client.contacts
const { data } = await client.contacts.list({ search: "John" });
const contact = await client.contacts.resolve({ phone_number: "+14155551234" });
const contact = await client.contacts.get("contact-id");
const interactions = await client.contacts.getInteractions("contact-id");
const memories = await client.contacts.getMemories("contact-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /contacts | List contacts (cursor-paginated) |
resolve(query) | GET | /contacts/resolve | Look up a contact by phone number or email |
get(contactId) | GET | /contacts/:id | Get contact by ID |
getInteractions(contactId) | GET | /contacts/:id/interactions | Get call/message history for a contact |
getMemories(contactId) | GET | /contacts/:id/memories | Get AI memories for a contact |
client.knowledgeBases
const kbs = await client.knowledgeBases.list();
const files = await client.knowledgeBases.listFiles("kb-id");
const urls = await client.knowledgeBases.getUploadUrls("kb-id", {
files: [{ name: "doc.pdf", content_type: "application/pdf" }],
});
await client.knowledgeBases.triggerChunking("kb-id");
await client.knowledgeBases.deleteFile("kb-id", "file-id");
await client.knowledgeBases.delete("kb-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list() | GET | /knowledge-bases | List all knowledge bases |
listFiles(kbId) | GET | /knowledge-bases/:id/files | List documents in a knowledge base |
getUploadUrls(kbId, body) | POST | /knowledge-bases/:id/upload-urls | Get pre-signed S3 upload URLs |
triggerChunking(kbId) | POST | /knowledge-bases/:id/trigger-chunking | Start document processing/chunking |
deleteFile(kbId, fileId) | DELETE | /knowledge-bases/:id/files/:fileId | Delete a file from a knowledge base |
delete(kbId) | DELETE | /knowledge-bases/:id | Delete a knowledge base |
client.workflowFolders
const { data } = await client.workflowFolders.list();
await client.workflowFolders.create({ name: "Production" });
const folder = await client.workflowFolders.get("folder-id");
await client.workflowFolders.update("folder-id", { name: "Updated" });
await client.workflowFolders.delete("folder-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /workflow-folders | List folders (paginated) |
create(body) | POST | /workflow-folders | Create a folder |
get(folderId) | GET | /workflow-folders/:id | Get a folder |
update(folderId, body) | PUT | /workflow-folders/:id | Update a folder |
delete(folderId) | DELETE | /workflow-folders/:id | Delete a folder |
client.mcp
const { data } = await client.mcp.list();
await client.mcp.create({ name: "My MCP", url: "https://..." });
await client.mcp.refresh("mcp-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
list(query?) | GET | /mcp | List MCP servers (paginated) |
create(body) | POST | /mcp | Register a new MCP server |
refresh(mcpId) | POST | /mcp/:id/refresh | Re-discover tools for an MCP server |
OAuth2 (auth_type: "oauth2"): set oauth2_credential_id to the UUID of an OAuth 2.0 integration credential (same org) configured with your provider’s token URL. Do not send auth_token; the API fetches a short-lived access token when creating, listing refresh, or when workflows run.
client.billing
const details = await client.billing.getDetails({
start: "2024-01-01",
end: "2024-01-31",
});
const totals = await client.billing.getTotals({
start: "2024-01-01",
end: "2024-01-31",
});
| Method | HTTP | Path | Description |
|---|---|---|---|
getDetails(query) | GET | /billing/usage/details | Detailed billing line items |
getTotals(query) | GET | /billing/usage/totals | Aggregated billing totals |
client.apiKey
const info = await client.apiKey.describe();
| Method | HTTP | Path | Description |
|---|---|---|---|
describe() | GET | /api-key/describe | Introspect the current API key (ID, name, org, etc.) |
Native scenarios and retained history
Create and execute scenarios through client.e2eScenarios. client.adversarialTests and client.adversarialSuites expose retained history reads only.
const { scenario } = await client.e2eScenarios.create({
targetUseCaseId: "workflow-id",
targetAgentNodePersistentId: "agent-persistent-id",
targetEnvironment: "production",
mode: "agent_isolated",
seeds: [],
name: "Booking probe",
adversarialPrompt: "Ask to book load L-7.",
});
await client.e2eScenarios.run(scenario.id, "selected-version-id");
const { messages } =
await client.adversarialTests.getRunMessages("legacy-run-id");
client.northstars
Northstars are quality criteria that define how the agent should behave. They are used to automatically grade conversations.
const { northstar } = await client.northstars.get("northstar-id");
await client.northstars.update("northstar-id", {
enabled: true,
priority: "high",
});
await client.northstars.delete("northstar-id");
// Get full regeneration history
const { history } = await client.northstars.getHistory("northstar-id");
// Rate a northstar (-2 = strongly wrong, +2 = strongly correct)
const { feedback } = await client.northstars.submitFeedback("northstar-id", {
correctness: 2,
feedback: "This criterion is perfect.",
trigger_regeneration: false,
});
await client.northstars.deleteFeedback("northstar-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
get(northstarId) | GET | /northstars/:id | Get a northstar |
update(northstarId, body) | PATCH | /northstars/:id | Update name, description, examples, category, priority, or enabled state |
delete(northstarId) | DELETE | /northstars/:id | Delete a northstar |
getHistory(northstarId) | GET | /northstars/:id/history | Get the full regeneration chain, oldest first |
submitFeedback(northstarId, body) | POST | /northstars/:id/feedback | Rate a northstar's correctness (−2 to +2), optionally trigger regeneration |
deleteFeedback(northstarId) | DELETE | /northstars/:id/feedback | Remove your feedback on a northstar |
client.customEvals
Custom evals test a specific prompt node against expected outputs or northstar criteria.
const { test } = await client.customEvals.get("eval-id");
await client.customEvals.update("eval-id", {
name: "Greeting check",
expected_response: "Hello, how can I help you?",
});
await client.customEvals.delete("eval-id");
// Run an eval
const { run_id } = await client.customEvals.run("eval-id", {
version_id: "v-id",
});
// Poll results
const { runs } = await client.customEvals.listRuns("eval-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
get(evalId) | GET | /custom-evals/:id | Get a custom eval |
update(evalId, body) | PATCH | /custom-evals/:id | Update messages, expected outputs, variables, or northstar IDs |
delete(evalId) | DELETE | /custom-evals/:id | Delete a custom eval |
run(evalId, body) | POST | /custom-evals/:id/run | Execute the eval asynchronously, returns run_id |
listRuns(evalId, query?) | GET | /custom-evals/:id/runs | List runs with pass/fail and judge reasoning |
client.nodeTests
Saved node tests run a node with fixed upstream values and compare its output to an expected output. They appear in the workflow's Tests tab and belong to the node of one version. Forking a version copies them.
const { test } = await client.nodeTests.create("node-id", {
name: "Load 123 transcript",
config: { overrides: { "upstream-persistent-id.transcript": "..." } },
expected_output: { carrier: "ACME", rate: 1200 },
ignored_fields: ["notes"],
});
const { run_id } = await client.nodeTests.run(test.id);
const { run } = await client.nodeTests.getRun(test.id, run_id); // poll until status !== "running"
| Method | HTTP | Path | Description |
|---|---|---|---|
list(nodeId) | GET | /nodes/:id/node-tests | List a node's saved tests |
create(nodeId, body) | POST | /nodes/:id/node-tests | Create a saved test |
get(id) | GET | /node-tests/:id | Get a saved test |
update(id, body) | PATCH | /node-tests/:id | Update any of name, overrides, expected or ignored fields |
delete(id) | DELETE | /node-tests/:id | Delete a saved test |
run(id) | POST | /node-tests/:id/run | Run against the node's current configuration |
listRuns(id, query?) | GET | /node-tests/:id/runs | List runs, newest first (limit, cursor) |
getRun(id, runId) | GET | /node-tests/:id/runs/:id | Get a run's output, pass/fail and mismatched fields |
Tests on branches: client.branches.*
On workspaces on branches, tests live on each branch: use the /branches/{branch_id}/... routes through client.branches.customEvals, .northstars, .nodeTests, .e2eScenarios and .testSuites. They take persistent IDs, which stay the same across edits and commits. Every object they return has id, its current revision, which changes after a commit, and persistent_id, which goes in paths; a node's is its persistent_id in client.branches.get(branchId). Edits land in the branch's working tree, and runs use its working commit. The flat routes above are for workspaces on versions, and refuse edits on branch workspaces with a pointer to the branch route.
const branchId = "branch-id";
const { data } = await client.branches.customEvals.listForNode(
branchId,
"prompt-persistent-id"
);
await client.branches.customEvals.update(branchId, data[0].persistent_id, {
name: "Renamed",
});
const { run_id } = await client.branches.customEvals.run(
branchId,
data[0].persistent_id
);
const { runs } = await client.branches.customEvals.listRuns(
branchId,
data[0].persistent_id
);
const { data: northstars, suggestions } =
await client.branches.northstars.listForNode(
branchId,
"prompt-persistent-id"
);
// Refresh proposes changes as suggestions; accept or dismiss them by persistent ID.
await client.branches.northstars.acceptSuggestions(branchId, {
suggestion_ids: suggestions.map((suggestion) => suggestion.persistent_id),
});
const { tests } = await client.branches.nodeTests.list(
branchId,
"node-persistent-id"
);
const { scenarios } = await client.branches.e2eScenarios.list(branchId);
await client.branches.e2eScenarios.run(branchId, scenarios[0].persistent_id);
client.issues
Issues (quality flags) are raised when a conversation fails a northstar or quality check.
await client.issues.update("issue-id", { status: "approved" });
| Method | HTTP | Path | Description |
|---|---|---|---|
update(issueId, body) | PATCH | /issues/:id | Update issue status (open / approved / rejected / closed) |
client.auditRemarks
Audit remarks are individual northstar grades attached to a conversation. Feedback on audit remarks improves future grading.
const feedback = await client.auditRemarks.getFeedback("audit-remark-id");
// Thumbs up — automatically adds the remark as a northstar positive example
await client.auditRemarks.submitFeedback("audit-remark-id", {
polarity: true,
});
// Thumbs down with attribution
await client.auditRemarks.submitFeedback("audit-remark-id", {
polarity: false,
issue_attribution: "northstar",
comment: "The northstar criteria was wrong here.",
});
await client.auditRemarks.deleteFeedback("audit-remark-id");
| Method | HTTP | Path | Description |
|---|---|---|---|
getFeedback(auditRemarkId) | GET | /audit-remarks/:id/feedback | Get your feedback for this remark, or null |
submitFeedback(auditRemarkId, body) | POST | /audit-remarks/:id/feedback | Submit thumbs up/down; a thumbs-up adds the remark as a northstar example |
deleteFeedback(auditRemarkId) | DELETE | /audit-remarks/:id/feedback | Delete your feedback |
Client access tokens (client.tokens)
Create a token on your backend using your API key, then pass it to a client app to read specific sessions or runs. Tokens use JWE encryption; treat them as opaque and use the returned expiry time.
// Your backend
const access = await client.tokens.create({
grants: [
{ resource: "session", resource_id: sessionId, actions: ["read"] },
{ resource: "run", resource_id: runId, actions: ["read"] },
],
ttl_seconds: 3600,
});
// Your client app
const reader = new HappyRobotClient({ apiKey: access.token });
const history = await reader.sessions.getMessages(sessionId);
POST /tokens accepts 1–10 grants. Every grant must be permitted by the API key. Supported resources are session and run; the only supported action is read. The lifetime defaults to 3600 seconds, with a minimum of 60 and a maximum of 86400. The response contains only token and expires_at.
A session grant permits its details, messages, and stream. A run grant permits those reads for sessions belonging to the run, plus GET /runs/{id}/sessions. Unsupported protected routes return 403; resources outside the grants return 404. Client tokens cannot mint tokens. Revoking or expiring the minting API key blocks subsequent client-token requests.
Client-token message reads hide system messages, internal events, reminders, tool results, and tool calls. They use the existing organization rate limit. Streams emit token_expiring 30 seconds before expiry, then token_expired and close at expiry. Request a fresh token from your backend and reconnect. Recover missed messages through paginated message reads and merge by message ID; the stream does not provide cursor replay.
Server configuration: client tokens use the existing ENCRYPTION_KEY (32 UTF-8 bytes), with HKDF-SHA256 deriving a separate key for happyrobot/client-access-token/v1. No additional secret or database migration is required. A missing key disables minting with 503; an invalid key fails startup. Rotating ENCRYPTION_KEY invalidates existing client tokens and also affects stored credential encryption.
Chat (client.chat + HappyRobotChatClient)
Build custom chat UIs powered by your workflows. Uses a two-tier auth model:
- Your server creates a scoped client token using the API key (keeps it secret)
- Your browser uses
HappyRobotChatClientwith that token for all chat operations
Server-side: Create a client token
// --- YOUR SERVER (e.g. Next.js API route, Express handler) ---
import { HappyRobotClient } from "@happyrobot-ai/sdk";
const client = new HappyRobotClient({ apiKey: process.env.HAPPYROBOT_API_KEY });
app.post("/api/chat-token", async (req, res) => {
const { token, expires_at } = await client.chat.createToken({
workflow_id: "your-workflow-id",
// Optional. Token lifetime in seconds. Default 3600 (1 hour), min 60, max 86400.
// ttl_seconds: 1800,
});
res.json({ token, expires_at });
});
Browser-side: HappyRobotChatClient
// --- YOUR BROWSER CODE (React, Vue, vanilla JS, etc.) ---
import { HappyRobotChatClient } from "@happyrobot-ai/sdk";
// 1. Get a client token from your server
const { token } = await fetch("/api/chat-token", { method: "POST" }).then((r) =>
r.json()
);
// 2. Initialize the browser-side client
const chat = new HappyRobotChatClient({ token });
// 3. Create a session
const { session_id } = await chat.createSession();
// 4. Connect bidirectional WebSocket
const connection = chat.connect(session_id, {
onResponseStart: () => {
// Show typing indicator
},
onResponseChunk: (content) => {
// Append streamed text to the UI
},
onResponseEnd: (content) => {
// Full response complete — hide typing indicator
},
onSessionClosed: (event) => {
// Session ended: event.status, event.reason, event.duration
},
// Auto-refresh: ~30s before the token expires the SDK calls this and
// forwards the result over the WebSocket. The connection stays open.
getToken: async () => {
const { token } = await fetch("/api/chat-token", { method: "POST" }).then(
(r) => r.json()
);
return token;
},
onTokenExpired: () => {
// Backstop: only fires if no valid refresh arrived in time
// (e.g. getToken not provided, network failure). Reconnect from scratch.
},
});
// 5. Send messages through the WebSocket
const ack = await connection.sendMessage({ content: "Hello!" });
console.log(ack.message.id); // server-assigned message ID
// 6. Send messages with file attachments
const artifact = await chat.uploadFile(fileBlob, "photo.png", "image/png");
await connection.sendMessage({
content: "Here's the photo",
artifacts: [artifact],
});
// 7. Get history (page reload, reconnect)
const { messages } = await chat.getHistory(session_id);
// 8. Clean up
connection.close();
Browser-side: File uploads
// Option A: Use the convenience method (handles all 3 steps)
const artifact = await chat.uploadFile(fileBlob, "photo.png", "image/png");
await connection.sendMessage({
content: "Here's the photo",
artifacts: [artifact],
});
// Option B: Manual 3-step flow for more control
const upload = await chat.getPresignedUpload({
filename: "photo.png",
mime_type: "image/png",
});
await fetch(upload.upload_url, {
method: "PUT",
body: fileBlob,
headers: { "Content-Type": "image/png" },
});
await chat.completeUpload({
artifact_id: upload.artifact_id,
s3_uri: upload.s3_uri,
filename: "photo.png",
mime_type: "image/png",
size_bytes: fileBlob.size,
});
await connection.sendMessage({
content: "Here's the photo",
artifacts: [
{
media_id: upload.artifact_id,
mime_type: "image/png",
filename: "photo.png",
size_bytes: fileBlob.size,
},
],
});
HappyRobotClient (server-side)
| Method | Description |
|---|---|
client.chat.createToken({ workflow_id, env?, ttl_seconds? }) | Create a scoped client token. ttl_seconds defaults to 3600 (1 hour). |
HappyRobotChatClient (browser-side)
| Method | Description |
|---|---|
chat.createSession() | Create a new chat session |
chat.connect(sessionId, handlers) | Open bidirectional WebSocket — returns ChatConnection |
chat.sendMessage(sessionId, { content, artifacts? }) | Send a user message via HTTP (fallback if WS unavailable) |
chat.getHistory(sessionId) | Get message history |
chat.uploadFile(file, filename, mimeType) | Upload a file (convenience method) |
chat.getPresignedUpload({ filename, mime_type }) | Get presigned S3 upload URL |
chat.completeUpload({ artifact_id, s3_uri, ... }) | Register uploaded artifact |
ChatConnection
| Method | Description |
|---|---|
connection.sendMessage({ content, artifacts? }) | Send a message via WebSocket. Returns a Promise that resolves with the server ack |
connection.close() | Close the WebSocket connection |
connection.ws | The underlying WebSocket instance |
WebSocket Events
Server → Client:
| Event | Fields | Description |
|---|---|---|
connected | session_id | Connection established |
response-start | content | AI started generating a response |
response-chunk | content | Partial response text |
response-end | content | Complete response text |
session-closed | session_id, status, reason, duration, timestamp | Session ended |
token-refresh-required | — | Sent ~30s before exp. SDK handles automatically when getToken is provided |
token-refresh-ack | expires_at | Server accepted the refreshed token; connection lifetime extended |
token-refresh-error | error | Refresh token was invalid or scope-mismatched; previous token still in force |
token-expired | — | Backstop: token expired without a valid refresh, connection is closing |
message-ack | id, message | Server confirmed the message was sent |
message-error | id, error | Server failed to send the message |
heartbeat | — | Keep-alive (every 15s) |
Client → Server:
| Event | Fields | Description |
|---|---|---|
message | content, artifacts?, id? | Send a user message. id is echoed back in ack/error |
token-refresh | token | Provide a fresh token to extend the connection. Sent automatically by the SDK when getToken set |
Token refresh
Tokens have a finite lifetime (default 1 hour, configurable via ttl_seconds on createToken). To keep long-lived connections alive without forcing the client to reconnect, the SDK supports in-band refresh:
- ~30s before the active token expires, the server sends
token-refresh-required. - The SDK calls your
getTokenhandler to fetch a fresh token from your backend. - The SDK sends
{ type: "token-refresh", token }over the WebSocket. - The server verifies the new token (scope must match: same
workflow_id,org,env) and replies withtoken-refresh-ack.onTokenRefreshed(expiresAt)fires on the client. - If no valid refresh arrives by exp, the server sends
token-expiredand closes the connection —onTokenExpiredfires as a backstop.
If you don't provide getToken, refreshes are skipped and the connection will close at exp (legacy behavior). When the same token is shared across multiple concurrent connections, each connection refreshes independently — they diverge to per-connection tokens after the first refresh.
Voice (client.voice + HappyRobotVoiceClient)
Build browser-side voice calls with AI agents powered by your workflows. Uses the same two-tier auth model as chat:
- Your server creates a scoped LiveKit token using the API key (keeps it secret)
- Your browser uses
HappyRobotVoiceClientwith that token to connect via WebRTC
Server-side: Create a voice token
// --- YOUR SERVER (e.g. Next.js API route, Express handler) ---
import { HappyRobotClient } from "@happyrobot-ai/sdk";
const client = new HappyRobotClient({ apiKey: process.env.HAPPYROBOT_API_KEY });
app.post("/api/voice-token", async (req, res) => {
const result = await client.voice.createToken({
workflow_id: "your-workflow-id",
data: { customer_name: "John" }, // optional — passed to the agent
// Optional. LiveKit token lifetime in seconds.
// Default 21600 (6 hours), min 60, max 86400 (24 hours).
// LiveKit does not refresh tokens on an active call.
// ttl_seconds: 3600,
});
res.json(result); // { url, token, room_name, run_id }
});
app.post("/api/live-session/:sessionId/listen-token", async (req, res) => {
const result = await client.voice.createToken({
session_id: req.params.sessionId,
});
res.json(result); // Hidden, subscribe-only observer token
});
Browser-side: HappyRobotVoiceClient
// --- YOUR BROWSER CODE (React, Vue, vanilla JS, etc.) ---
import { HappyRobotVoiceClient } from "@happyrobot-ai/sdk/voice";
// 1. Get a voice token from your server
const { url, token } = await fetch("/api/voice-token", { method: "POST" }).then(
(r) => r.json()
);
// 2. Create the voice client and connect
const voice = new HappyRobotVoiceClient({ url, token });
const connection = await voice.connect({
onConnected: () => {
// Call started — microphone is automatically enabled
},
onAgentConnected: (participant) => {
// AI agent joined the room
console.log("Agent:", participant.identity);
},
onDisconnected: (reason) => {
// Call ended
},
onReconnecting: () => {
// Connection temporarily lost
},
onReconnected: () => {
// Successfully reconnected
},
onError: (error) => {
console.error("Voice error:", error);
},
});
// 3. Mute / unmute
await connection.mute();
console.log(connection.isMuted()); // true
await connection.unmute();
// 4. End the call
await connection.disconnect();
To listen to an existing call without publishing audio or affecting the AI
agent, create a token with session_id and use listen() in the browser:
const { url, token } = await fetch(
`/api/live-session/${sessionId}/listen-token`,
{ method: "POST" }
).then((r) => r.json());
const voice = new HappyRobotVoiceClient({ url, token });
const listener = await voice.listen();
// If the browser later blocks playback, call this from a click handler:
await listener.startAudio();
// Stop listening without affecting the call:
await listener.disconnect();
Set should_takeover: true when creating a session token to retain the
existing takeover behavior, which removes the AI agent from the call.
HappyRobotClient (server-side)
List the voices available to the current workspace in its cluster. Use a language prefix for all accents, or a locale for a location-specific result:
const voices = await client.voice.list({ language: "en-GB" });
for (const voice of voices) {
console.log(voice.id, voice.name, voice.locales);
}
voice.id is the value used in workflow agent.voices configuration.
| Method | Description |
|---|---|
client.voice.list({ language? }) | List voices available to the current workspace. language accepts prefixes like en or locales like en-GB. |
client.voice.createToken({ workflow_id, data?, env?, ttl_seconds? }) | Create a LiveKit token for a new voice call. |
client.voice.createToken({ session_id, should_takeover?, ttl_seconds? }) | Observe a live session, or take it over when should_takeover is true. |
HappyRobotVoiceClient (browser-side)
| Method | Description |
|---|---|
new HappyRobotVoiceClient({ url, token }) | Create client with LiveKit credentials |
voice.connect(handlers?) | Connect and enable the microphone — returns VoiceConnection |
voice.listen(handlers?) | Connect without microphone access or publishing — returns VoiceListenerConnection |
VoiceConnection
| Method | Description |
|---|---|
connection.disconnect() | End the call and disconnect from the room |
connection.mute() | Mute the local microphone |
connection.unmute() | Unmute the local microphone |
connection.isMuted() | Check mute state |
connection.room | Underlying LiveKit Room instance for advanced use cases |
VoiceListenerConnection
| Method | Description |
|---|---|
listener.disconnect() | Stop listening without affecting the call |
listener.startAudio() | Resume audio playback from a browser user gesture |
listener.room | Underlying LiveKit Room instance for advanced use cases |
Room Events
| Handler | Description |
|---|---|
onConnected | Connected to the LiveKit room |
onDisconnected | Disconnected from the room |
onAgentConnected | AI agent participant joined the room |
onTrackSubscribed | Remote audio track subscribed (auto-plays) |
onTrackUnsubscribed | Remote audio track unsubscribed |
onReconnecting | Connection temporarily lost — attempting to reconnect |
onReconnected | Successfully reconnected |
onError | An error occurred |
Pagination
List methods that are paginated return a PaginatedResponse<T>:
interface PaginatedResponse<T> {
data: T[];
pagination: {
page: number;
page_size: number;
total_pages: number;
total_records: number;
has_next_page: boolean;
has_previous_page: boolean;
};
}
For resources that support listAll(), use the async generator to iterate all pages automatically:
for await (const workflow of client.workflows.listAll({ folder_id: "..." })) {
console.log(workflow.name);
}
Error Handling
import {
ApiError,
AuthenticationError,
NotFoundError,
} from "@happyrobot-ai/sdk";
try {
const wf = await client.workflows.get("nonexistent");
} catch (err) {
if (err instanceof NotFoundError) {
console.log("Workflow not found");
} else if (err instanceof AuthenticationError) {
console.log("Invalid API key");
} else if (err instanceof ApiError) {
console.log(err.status, err.message);
}
}
Shared test suites
Use client.testSuites for workflow-scoped custom/scenario collections. create accepts the shared useCaseId, name, origin, generationConfig, coverageScope, folderId, and members fields. Membership changes preserve definitions and history.
const { suite } = await client.testSuites.create({
useCaseId: "workflow-id",
name: "Booking regression",
members: [{ kind: "custom", id: "test-id" }],
});
await client.testSuites.membership(suite.id, {
members: [{ kind: "e2e", id: "scenario-id" }],
});
const { suite_run_id } = await client.testSuites.run(suite.id, "version-id");
const { run, results } = await client.testSuites.results(suite_run_id);
await client.testSuites.delete(suite.id);
AI generation runs once from generationConfig with a concrete version via generate(suiteId, versionId). After it succeeds, edit definitions and membership manually. Suite coverage guides generation and does not override existing test grading.