REST Facade for Custom Connectors

The REST facade exposes each HG MCP Server tool as its own REST action under /api/powerautomate/<tool_name>, with a Swagger 2.0 spec you can import into a Power Platform custom connector or any other OpenAPI consumer (Azure Logic Apps, n8n, Zapier).

Building a Copilot Studio agent?

Use HG Insights Connect for Microsoft instead. It is the certified connector in the Microsoft catalog, needs no custom connector, and connects your agent to the HG MCP Server directly. Use this facade only when you need one REST action per tool.

Permitted use

The facade is for agents and assistants that reason over HG Insights data. It is not licensed for deterministic record-by-record processing. For example, an Apply to each loop that reads rows from Dataverse, SharePoint or a CRM and writes HG fields back is outside permitted use at any volume. For that, use the HG Insights API or the HG SaaS application.

Credits, rate limits and caching are the same as on the main /api/mcp endpoint.

Key URLs

Purpose	URL
Swagger 2.0 spec (for connector import)	https://phoenix.hginsights.com/api/powerautomate/openapi.json
Tool invocation	POST https://phoenix.hginsights.com/api/powerautomate/<tool_name>
Tool catalog (public, no auth)	GET https://phoenix.hginsights.com/api/powerautomate

Import a custom connector

1. In make.powerautomate.com, go to Custom connectors and select + New custom connector → Import an OpenAPI file (or Import from URL if your tenant allows it).
2. Upload the spec, downloaded with:

   curl https://phoenix.hginsights.com/api/powerautomate/openapi.json -o hg-insights.json

   or paste the spec URL.
3. In the wizard, leave General as prefilled. On Security, the authentication type is API Key, with parameter name x-api-key in the Header.
4. Select Create connector, then on Test create a connection with your phx_... key (a User-scope key, see Keys, credentials and consumption), and test an action such as CompanyFirmographic (the wizard lists each tool by its PascalCase operation ID) with companyDomain: cisco.com.

Authentication

The facade accepts either header:

x-api-key: phx_...
Authorization: Bearer phx_...

The spec advertises x-api-key, so connection users paste the raw key with no Bearer prefix.

Sample request

curl -sS https://phoenix.hginsights.com/api/powerautomate/company_firmographic \
  -H "x-api-key: $PHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyDomain":"cisco.com"}'

Response bodies match each tool's output schema exactly, with no JSON-RPC envelope.

Available actions

The discovery endpoint is the authoritative list, with input and output schemas:

curl -sS https://phoenix.hginsights.com/api/powerautomate | jq '.tools[].name'

It covers the HG v1 catalog tools (get_product_category, get_vendor_information and others), company intelligence, contact, SEC and government tools, plus the admin_* tools described in Admin Operations. Low-level tools such as hg_data_query and hg_catalog are not exposed through the facade; use the main /api/mcp endpoint for those.

Admin and data tools follow the same key-scope split as MCP: an admin_* tool needs an Admin-scope key owned by a current org admin, and a data tool needs a User-scope key. A mismatch in either direction returns 403 forbidden_admin_scope.

Error responses

Errors return a plain JSON body with no JSON-RPC envelope, usually { "error": <code>, "message": <text>, "details"?: <object> }:

Status	Error code	When
400	validation_failed	The body failed schema validation. details carries the issues
400	invalid_json	The body is not valid JSON
400	invalid_parameters	Tool-level validation failed (for example, neither companyDomain nor hg_id given)
401	unauthorized	Missing or invalid API key
402	credit_limit_exceeded	Your organization has used its credit allocation
403	forbidden_admin_scope	The key's scope doesn't match the tool: a data tool called with an Admin-scope key whose owner is still an org admin, or an admin_* tool called with a User-scope key or by a key whose owner is no longer an org admin
404	tool_not_found	The tool isn't exposed through the facade, or this tool version is limited to enrolled organizations
424	missing_integration	Your organization is missing a required integration. details.required lists it
429	Rate limit exceeded or exempt_rate_limit	Rate limit reached. Honor the Retry-After header
502	tool_execution_failed	An upstream tool or API failed
500	internal_error	Unexpected server error
503	outbound_capacity	HG is shedding load. Retry with backoff

An admin_* action that fails on its own rules returns that action's status (400 by default) with its own code in error, for example already_member or last_admin, and errorCategory: "admin_action_failed".

Related

• HG Insights Connect for Microsoft: the certified MCP connector for Copilot Studio.
• Authentication: API keys and OAuth.
• Best Practices: rate limits, error handling and optimization.