Home›API, webhooks and MCP
Your Helios data, in the rest of your business.
Installer Pro includes a documented REST API and webhooks. Your own systems can create and update leads, customers, companies and tasks, read proposals, invoices, systems and their daily energy, and hear about what happens — a lead converting, an invoice being paid, a system going offline — the moment it happens. And anyone on your team can connect Claude, ChatGPT or Copilot to Helios through its MCP server. This page explains what each reaches and how it is secured; the reference documentation has every endpoint.
Connect Claude, ChatGPT or Copilot: the Helios MCP server
Helios runs its own MCP server. Add it to Claude, ChatGPT, Copilot or any AI app that accepts custom connectors, and ask about your fleet, customers, leads, proposals and invoices in plain language — answered from your Helios records, next to your email and documents.
Connect in three steps
- An account admin switches on the Connect your AI apps add-on in Settings. It has no price of its own.
- In your AI app, add a custom connector (MCP server) with the address shown in Settings › Connected AI apps.
- The app opens a Helios page: sign in and choose Allow.
What it can and cannot do
- Read-only. The app can look records up and query them; it cannot create, change or delete anything.
- As you. Each person connects their own app, and it sees exactly what their role lets them see.
- Five tools. List what can be queried, describe a record type, run a query, read customer health scores, and look up how something is done in Helios.
- Standard sign-in, no key to paste. OAuth with PKCE and dynamic client registration. Access tokens last an hour; refresh tokens rotate, and an app left unused for 30 days has to be allowed again. Every call checks the person, the organisation, the add-on and the admin switch afresh.
- Mailbox and calendar data stay in Helios. Email filed from a connected mailbox, calendar events and time off are never passed to an AI app.
- Yours to switch off. Anyone can disconnect their app under Settings › Connected AI apps. An account admin sees every connected app in the organisation and can switch connections off for everyone at once.
- You choose who may connect. By default Owners, Admins, Managers and Staff; never the Read-only or Accountant roles. Custom roles start without it.
- On the record. Every call an AI app makes is in the audit log.
- Your app, your AI subscription. Answers go to the app you connected, not to our AI provider, and do not use your Helios AI allowance. What the app does with them is covered by its own terms.
What the API reaches
JSON over HTTPS at api.helios-energy.app, with the same records your team works with in Helios.
| Records | What a key can do |
|---|---|
| Leads | List, read, create, update |
| Customers | List, read, create, update |
| Companies | List, read, create, update |
| Tasks | List, read, create |
| Proposals | List, read |
| Invoices | List, read |
| Pipeline stages | List |
| Systems | List, read, and each system’s daily energy |
| Webhook subscriptions | List, create, delete — and list the events the key may receive |
A me endpoint tells an integration who it is acting as and which records it may reach, so it never has to guess.
Webhooks: 20 events
Choose the events a webhook receives. Each delivery says what happened and to which record.
| Record | Events |
|---|---|
| Lead | created, updated, stage changed, converted |
| Customer | created, updated, stage changed |
| Company | created, updated |
| Task | created, status changed |
| Proposal | created, status changed, accepted |
| Invoice | created, status changed, paid, overdue |
| System | offline, back online |
By default a delivery carries the record’s ID and where to fetch it, so the record itself only ever travels over an authenticated API call. Choose full payloads if you would rather receive the record in the webhook. A webhook made with a key only receives events for records that key’s role may see.
Deliveries you can rely on
- Signed. Every delivery carries an
X-Webhook-Signatureheader: an HMAC-SHA256 of a timestamp and the raw body, made with your webhook’s secret, so your endpoint can check that it came from Helios and that it is recent. You can add an authorisation header of your own as well. When you rotate the secret, the old one keeps signing alongside the new one for 24 hours, so you can switch without missing anything. - Only to endpoints that are yours. Nothing is delivered until your endpoint answers a verification challenge, and it is asked again every 30 days. Your organisation can limit webhooks to domains you list, and well-known request-inspection services are refused.
- Retried, then kept. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, then 2, 6, 12 and 24 hours — eight attempts over about 45 hours. The delivery log shows every attempt; resend one, or resend every failed delivery at once.
- Switched off only for a real outage. A webhook is switched off only after 20 failures in a row and 24 hours without a single successful delivery. While it is off, deliveries wait instead of failing, and go out when you switch it back on; one switched off automatically keeps collecting events for seven days.
- Changes need a second factor. Creating a webhook, changing its URL or its domain list, or asking for full payloads needs your two-step code (or your password), and every owner of the account is emailed.
Keys and tokens
- Capped by a role. An account admin creates keys in Settings › API and webhooks. Each key has a role, and it can never do more than that role or than the person who created it — whose records it reaches included. The key is shown once.
- Personal data only when you allow it. A new key sees no personal data — names, email addresses, phone numbers, addresses and free-text notes come back empty — unless you tick that it may.
- Limited to your networks. Restrict a key to the IP addresses or ranges your integration calls from.
- Always expiring. New keys default to 90 days and can last up to a year. The person who made the key and the account owners are reminded 14 and 3 days before it expires.
- Watched. Creating or rotating a key needs your two-step code (or password), and the owners are emailed. They are emailed again when a key is used unusually — from a new network or country, in a sudden spike, or with repeated refusals — and a key can be set to suspend itself when that happens.
- Short-lived tokens if you prefer them. An integration can exchange its key for a one-hour access token (OAuth 2.0 client credentials), with the key itself or with an assertion signed by a private key you register (
private_key_jwt). - Fair use. Up to ten keys can be active, and together they share your plan’s budget of 120 requests a minute; a single key can be held to less.
What it takes
The API and webhooks are part of Installer Pro. Xero, QuickBooks and 3CX are connected from Settings on the same plan, with no API work at all. The MCP connection is an add-on with no price of its own. For anything else, any tool or service that can make an HTTPS request can use the API, and any endpoint that can answer the verification challenge can receive webhooks.
The reference documentation
Every endpoint and every event payload is documented, with search and a page per endpoint: the API at api.helios-energy.app/api/public/v1/docs and webhooks at api.helios-energy.app/api/public/v1/docs/webhooks.
Read next
The Helios Platform page covers the records the API exposes. Pricing has the plans. The FAQ answers the rest.
Planning an integration?
Tell us what you want to connect, and we will walk through it on a demo.