API Reference

Overview

This page documents the public endpoints the ClearPath widget talks to at runtime. The base URL for all of them is https://get-clearpath.com/api. You do not normally call these yourself, the widget does, but it helps to know what is happening.

There are two public endpoints today: one the widget reads to learn how to render, and one it writes to for usage analytics. Both are scoped to a single account ID.

Authentication and domain rules

These endpoints do not use an API key. Instead, they are tied to your account ID and protected by domain binding. The config endpoint checks that the calling domain matches the domain registered for that account, and returns configuration only for a domain that is allowed.

This is why the same snippet will not work if you copy it onto an unregistered domain. Register every domain and subdomain you plan to use in the dashboard first.

GET /api/widget/config/{accountId}

This is the endpoint the widget calls first. Given an account ID in the path, it returns the settings the widget needs to decide what to render. The request must come from the registered domain, otherwise no usable config is returned.

The response is a JSON object with four top level fields: known, tier, features, and config. The widget reads these to know whether the account is valid, which plan it is on, which features to show, and how the button and panel should look.

• known: a boolean, true when the account ID is recognized.
• tier: the plan name, for example starter, pro, or agency.
• features: the set of tools and profiles enabled for this account, so free and paid features can differ.
• config: appearance and behavior settings such as button position, color, and default language.

POST /api/widget/event/{accountId}

This is the analytics beacon. When a visitor interacts with the widget, it sends a small event to this endpoint so your dashboard can report real usage. The account ID in the path ties the event to your site.

Each event carries a type. There are three types today, and together they let ClearPath show how often the widget was seen, opened, and actually used.

• load: the widget appeared on a page.
• open: a visitor opened the widget panel.
• tool: a visitor activated a specific tool, so you can see which tools are popular.
• The call is fire and forget from the visitor's browser and does not block the page.

Account management

There is no public write API for account management yet. Creating sites, registering domains, changing appearance, choosing which tools appear, and generating your accessibility statement are all done in the dashboard.

If you have a use case that needs programmatic account management, tell us. For now, treat the two runtime endpoints above as the full public surface.

Versioning and stability

These endpoints back the live widget, so we keep them backward compatible. New fields may be added to the config or event payloads over time, and your integration should ignore fields it does not recognize rather than break on them.

Because the widget loads its own script from get-clearpath.com, you generally get endpoint updates automatically without changing your snippet.