API

Use the REST API when your own systems need direct access to HAL data.

The API is the lowest-level integration surface. Use it for project data, workflow updates, and customer records when you are integrating HAL into your own backend.

Base URL

https://api.chatwithhal.com/api

Authentication

HAL exposes more than one HTTP surface, so the authentication method depends on which route family you are calling.

/api/widget/* is designed for customer-facing widget flows and uses project identification plus visitor identity input
/api/* account routes use bearer-token authentication for signed-in HAL users and first-party backends
/api/v1/* public integration routes use X-API-Key

Authorization: Bearer YOUR_TOKEN
X-API-Key: YOUR_API_KEY

Choose the right route family

Widget identify routes

Use these when your product or backend needs to push end-user, contact, or company context into HAL for a visitor session.

Account-authenticated routes

Use these when a signed-in HAL workspace owner or internal backend is managing records directly.

Public API key routes

Use these for external integrations that need conversations and contacts through /api/v1.

Important note for CRM and identity sync

If your goal is to send custom contact or company information from your app into HAL, use the widget-facing identify flow rather than the current /api/v1 surface.

The current public API key routes cover conversations and contacts, but they do not yet expose visitor/company metadata write endpoints. For customer identity and CRM enrichment tied to a widget visitor, see the visitor API details and widget identification docs.

That widget route family also includes CRM write endpoints such as POST /api/widget/set-stage and POST /api/widget/set-deal, which back window.HalWidget.setStage(...) and window.HalWidget.setDeal(...) in the browser widget.

What to use the API for

Operational integrations

Push or sync data between HAL and the rest of your stack when the built-in UI is not enough.

Custom product flows

Wire up internal tools, admin panels, or provisioning systems to the same project data HAL uses.

Controlled automation

Use the API when you need system-to-system actions beyond the approval-gated Manager experience.

Typical resources

Projects, visitors, and conversations
CRM companies, contacts, and stages
Knowledge-base and help-center content
Team configuration and related settings

When to use MCP instead

If you are connecting an external AI client and want tool-style access rather than raw REST integration, use the hosted HTTP MCP endpoint instead of building your own orchestration on top of the REST API.

Related docs

Pair the API with the right layer.

Use MCP for AI clients, OAuth for delegated access, and the widget for customer-facing entry points.

Visitor API details Widget identification Read MCP docs Read OAuth docs