Helpy developer guide

Overview

There are three ways to connect anything to Helpy. All of them run with exactly the permissions and data scope of the user who connected, and follow any change immediately:

The full OpenAPI 3.1 description of the REST API (for Postman, Swagger and SDK generators):

https://helpy.ai/api/v1/openapi.json

Connect an AI app in two minutes

One link for every app. The app discovers sign-in by itself (OAuth): you sign in to Helpy once and approve — no key to copy. Step-by-step setup is inside Helpy under Settings → AI connections.

https://helpy.ai/api/mcp

{
  "mcpServers": {
    "helpy": {
      "url": "https://helpy.ai/api/mcp"
    }
  }
}

mcp_servers:
  helpy:
    url: "https://helpy.ai/api/mcp"
    auth: oauth

# then run: hermes mcp login helpy

claude mcp add --transport http helpy https://helpy.ai/api/mcp

{
  "servers": {
    "helpy": {
      "type": "http",
      "url": "https://helpy.ai/api/mcp"
    }
  }
}

With an API key instead of sign-in (Hermes on a server, n8n, any MCP client without OAuth): send the header Authorization: Bearer <key>.

mcp_servers:
  helpy:
    url: "https://helpy.ai/api/mcp"
    headers:
      Authorization: "Bearer ${HELPY_API_KEY}"

How the MCP server works

• Transport: stateless Streamable HTTP (JSON-RPC over POST) — protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
• Tools: the same tools as the Helpy assistant (about 90) — the app only sees what the user is allowed to do in their company, plan and installed apps.
• Reads run immediately. Any change returns a preview with an action_id and does nothing; after the user agrees in the chat the app calls helpy_confirm_action. There are also helpy_cancel_action and helpy_undo_action (for reversible changes, within minutes).
• Changes that affect many customers need acknowledge_bulk=true after the user confirms the count.
• search and fetch: unified search over customers, conversations and the help center (compatible with ChatGPT Deep Research).
• Ready-made prompts appear as shortcuts in Claude and Cursor:

Limit tools to groups: append group names to the link, comma-separated, e.g. /api/mcp/crm,inbox,tasks. Account, help and approval tools are always included.

Authentication

OAuth 2.1 (for apps a user connects themselves):

API keys (for systems and automation): Helpy → Settings → AI connections → API keys. The key is shown once and works with both the MCP server and the REST API. “Allow changes” grants helpy:write.

Authorization: Bearer hlp_sk_YOUR_KEY

REST API v1

• Base URL: https://helpy.ai/api/v1
• Responses are always { "data": ..., "meta"?: ... } and errors { "error": { "code", "message" } }.
• Cursor pagination: send meta.nextCursor as ?cursor= on the next request.
• Translated labels (stage and service names) default to Arabic — use ?locale=en or Accept-Language: en for English.
• Anything outside the user's data scope returns 404 as if it didn't exist.

curl -X POST https://helpy.ai/api/v1/leads \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara Ahmed","phone":"+966501112233","email":"sara@example.com","tags":["expo"]}'

curl -X POST https://helpy.ai/api/v1/tasks \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Sara","leadId":"LEAD_ID","dueAt":"2026-11-01T09:00:00Z","priority":"HIGH"}'

curl -X POST https://helpy.ai/api/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer hlp_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"أهلاً سارة، عرض السعر في الطريق 👋"}'

const res = await fetch("https://helpy.ai/api/v1/leads?search=Sara", {
  headers: { Authorization: `Bearer ${process.env.HELPY_API_KEY}` },
});
const { data, error } = await res.json();

import os, requests

res = requests.get(
    "https://helpy.ai/api/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HELPY_API_KEY']}"},
)
tasks = res.json()["data"]

Errors and limits

• REST: 240 reads and 60 writes per minute per connection.
• MCP: 120 requests per minute per connection.
• Every response carries Helpy-Api-Version and X-RateLimit-Limit.

Webhooks

In Helpy → Apps → Zapier/Webhooks add your URL and pick events: lead.created and lead.updated. Each delivery is a JSON POST, retried up to 6 times until your URL answers 2xx.

{
  "event": "lead.created",
  "data": { "id": "…", "name": "Sara Ahmed", "phone": "+9665…", "status": "NEW", "createdAt": "…" },
  "firedAt": "2026-10-28T12:00:00.000Z"
}

Verify the request comes from Helpy: the X-Webhook-Signature header is sha256=HMAC-SHA256(raw body, webhook secret).

import { createHmac, timingSafeEqual } from "node:crypto";

function fromHelpy(rawBody, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return header?.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Security and privacy

• Every request re-checks the user, permissions and data scope from the database — nothing is cached in the token.
• Tokens and keys are stored as SHA-256 hashes only, and no secret is ever logged.
• Users disconnect any app or key instantly, and owners can disconnect their team's. “Sign out everywhere” and password changes disconnect everything.
• Connecting, disconnecting, key creation and every change are written to the audit log.
• In MCP: customer messages and notes are treated as data, not instructions, and changes need explicit approval.
• The Helpy team can turn connections off for the whole platform or a single company at once.