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, plus simple tracked events through POST /api/widget/track, which backs window.HalWidget.track(...) in the browser widget.

Route selection for CRM sync

Use /api/widget/identify when a product session or signed-in user should be mapped to HAL contacts and companies
Use /api/widget/set-properties for follow-up visitor/contact metadata writes after identify
Use /api/widget/track for milestone events with a required name and optional scalar value
Use /api/widget/set-stage and /api/widget/set-deal when the widget-side session should push company stage or deal changes
Use account-authenticated /api/contacts and /api/companies routes when an authenticated HAL workspace user or first-party backend manages CRM records directly
Use /api/v1 when an external integration with an API key only needs conversation or contact access

Current CRM write surfaces

Widget-facing routes

Visitor identity, linked companies, milestone event tracking, stage sync, deal sync, and property updates for customer-facing sessions.

Account-authenticated routes

Direct contact and company CRUD for signed-in HAL users and internal backends acting on behalf of a workspace.

Public API key routes

Conversations and contacts only today; visitor-company enrichment is intentionally outside this surface for now.

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 CRM docs Read MCP docs Read OAuth docs