API

The Hailer API is the interface to the Hailer platform: everything the web and mobile clients do - creating activities, sending messages, running insights, managing apps and workspaces - is done through the same endpoints documented here, so anything a user can do, an integration or an agent can do too.

This page takes you from nothing to your first authenticated call. It's a few paragraphs long - reading it end to end will save you time later.

Base URLs

Environment	Base URL
Production	https://api.hailer.com
Staging (sandbox)	https://api.hailer.biz

The staging backend is a playground for new versions; its database may be cleared from time to time. If you build against it, let us know so we can warn you before data is dropped.

Two ways to interact

There are two transports:

• @hailer/cli - a Node.js client (and SDK) that connects over Socket.IO. This is the recommended way to call the API, and every example in these docs uses it. Because it uses Socket.IO it also receives real-time signals when data changes.
• HTTP REST - call any endpoint with a plain HTTP POST. Simple and language-agnostic, but it does not deliver real-time signals. See Under the hood: the HTTP path.

Authentication

Two credential types work with either transport:

• User API key (recommended for scripts, integrations, and agents) - a revocable key tied to a user. Create one with v3.userApiKey.create. Prefer this over embedding a password.
• Username and password - the user's login email and password.

Connect with @hailer/cli

Install the client:

npm install @hailer/cli

With a user API key:

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  userApiKey: 'userapikey_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy',
});

With username and password:

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

host defaults to https://api.hailer.com, so you can omit it in production.

Your first call

Once connected, call any endpoint by name with an array of positional arguments. v2.core.init is a good first call - it bootstraps the initial application state (the current user, their workspaces, and more):

const state = await client.request('v2.core.init', []);
console.log('Connected as:', state.user.email);

On failure an endpoint returns the standard Hailer error object { code, msg, details?, debug? }.

The data model

Most of the API revolves around a small set of concepts:

• Workspace - the top-level container an account belongs to (formerly called a network).
• Workflow - a configurable process definition; its records are activities.
• Activity - a single record inside a workflow, constrained by that workflow's fields and phases.
• Discussion - a conversation thread and its messages.
• App, Insight, Product - installable apps, saved analytics, and marketplace products.

Workflows, phases, and fields have stable keys that can be used in place of raw ids in many calls.

Under the hood: the HTTP path

If you cannot use the Node client, every endpoint is also reachable over HTTP REST. The operator goes in the path (under /api) and the arguments are the JSON POST body.

1. Log in to get a session key:

curl -H "Content-Type: application/json" \
  -d '["you@example.com", "password"]' \
  https://api.hailer.com/api/login

The response is a session key string. (This is the same value @hailer/cli exposes as client.sessionKey.)

2. Call any endpoint by sending the session key as the hlrkey header:

curl -s -H "Content-Type: application/json" -H "hlrkey: <session-key>" \
  -d '[{ "subject": "Posting via API", "text": "Cool post from API." }]' \
  https://api.hailer.com/api/wall2/new_post

Arguments can also be sent as { "args": [...] } or as a key-mapped object ({ "0": ..., "1": ... }) for backwards compatibility, but a plain JSON array is the simplest form.

Guides

• Permissions - workspace roles, workflow and phase permissions, custom role permits, and how they resolve.
• Insights - turn workflow data into a SQL-queryable result and expose it outside Hailer.

Reference

Browse every module and endpoint in the reference, grouped by API version. Each page lists an endpoint's parameters, a runnable example, its return shape, and its auth requirement - all generated directly from the API source, so they track the code.