Phano Platform

API and MCP documentation

Plug Phano's composite intelligence into your tools. Detect at-risk accounts to secure retention, spot expansion signals to accelerate revenue, right where your Customer Success and Account Management teams already work.

RESTMCPPrecomputed dataRead-only

Full OpenAPI contract (import it into Postman, Insomnia or an agent)

Path 1: REST API

For your scripts, no-code automations and spreadsheets. Any tool able to make an HTTP request with a header.

Zapier, Make, n8n, Python, Node.js, Google Sheets, Excel.

Get started

Path 2: MCP

For AI agents. The server exposes 6 tools the assistant calls on its own, without you writing any code.

Claude Desktop, Cursor, VS Code, Windsurf, custom MCP client.

Configure

Foundations

Shared by both paths

A single API key, the same scopes, the same errors and the same limits apply whether you go through REST or MCP.

Authentication and scopesCommon

All requests (REST and MCP) authenticate with the same key, in the headerAuthorization:

Authorization: Bearer pk_live_xxxx

Create the key in Settings > API keys (shown only once). Scopes determine what the key can read. A key withoutread:stakeholdersreceives accounts and diagnostics, but contact names are masked.

Scope	Description	Endpoints
read:portfolio	Portfolio summary and risks	/v1/portfolio/summary, /v1/portfolio/risks
read:accounts	Account list and intelligence	/v1/accounts, /v1/accounts/{id}/intelligence
read:stakeholders	Contact names and roles (masked without this scope)	Any response containing stakeholders
read:all	All permissions + /v1/status	All endpoints + /v1/status

ErrorsCommon

Stable format: { "error": { "code", "message" } }. Over MCP, these errors are returned through the matching JSON-RPC codes (for example insufficient scope = -32003).

Code	HTTP	Description
unauthorized	401	Invalid, revoked or expired API key
forbidden	403	Insufficient scope for this endpoint
validation_error	400	Invalid parameter (format, value)
not_found	404	Resource not found
rate_limit_exceeded	429	Request limit exceeded (see Retry-After)
internal_error	500	Server error

Rate limitsCommon

3 levels of limiting:

Burst: 50 requests / 10 seconds per key
Daily: 10,000 requests / day per organization
Circuit breaker: temporary 429 (Retry-After 60s) if more than 50% 5xx errors over 1 minute

Response headers:

X-RateLimit-Limit: burst limit
X-RateLimit-Remaining: remaining requests
X-RateLimit-Reset: reset epoch
X-RateLimit-Limit-Daily: daily quota (10,000)
Retry-After: seconds before retry (if 429)

Path 1

REST API

Read-only HTTP GET endpoints. For your scripts, your no-code automations and your spreadsheets.

60-second quickstart

1. Create your API key

In Settings > API keys. Pick the scopes you need. The key is shown only once.

2. Make your first call

curl -H "Authorization: Bearer <your-api-key>" \
  https://phano.ai/api/v1/portfolio/summary

3. Read the response

Every response follows the same envelope: data (the content) andmeta (freshness and request identifier).

{
  "data": {
    "total_arr": 1250000,
    "total_arr_display": "1 250 000 EUR",
    "total_accounts": 42,
    "health_distribution": {
      "critical": { "count": 5, "percentage": 12 },
      "warning":  { "count": 9, "percentage": 21 },
      "healthy":  { "count": 28, "percentage": 67 }
    },
    "diagnostics_by_severity": { "critical": 3, "high": 7, "opportunity": 4 }
  },
  "meta": {
    "computed_at": "2026-06-08T04:35:00Z",
    "freshness": "il y a 6h",
    "composite_in_progress": false,
    "request_id": "b1f2..."
  }
}

REST reference

Base: https://phano.ai/api/v1. The full machine contract (response schemas, types) lives at openapi.json.

Endpoint	Scope	Description
GET/portfolio/summary	read:portfolio	Total ARR, health distribution, renewals, diagnostics by severity
GET/portfolio/risks	read:portfolio	At-risk accounts sorted by severity then confidence
GET/accounts	read:accounts	Account list (filters + cursor pagination)
GET/accounts/{id}/intelligence	read:accounts	Diagnostic, stakeholders and health of one account
GET/status	read:all	Latest composite run, accounts analyzed, connections

Available filters on /accounts

phase: engagement, disengagement, silence, rupture, churn
health_min / health_max: health score (0 to 100)
search: search by name (min 2 characters)
limit: 1 to 100 (default 20), cursor: pagination

Chain two calls: from portfolio to a single account

Per-account endpoints expect an id. Fetch it from the list first, then request the detailed intelligence.

# 1. List accounts (grab an id)
curl -H "Authorization: Bearer <your-api-key>" \
  "https://phano.ai/api/v1/accounts?limit=5"

# 2. Intelligence for one account
curl -H "Authorization: Bearer <your-api-key>" \
  https://phano.ai/api/v1/accounts/<id>/intelligence

Full example (Python)

import requests

headers = {"Authorization": "Bearer <your-api-key>"}
r = requests.get("https://phano.ai/api/v1/portfolio/risks", headers=headers)
risks = r.json()["data"]

for risk in risks:
    print(f"{risk['account']['name']}: {risk['diagnostic']['severity_display']}")

Full example (JavaScript)

const res = await fetch("https://phano.ai/api/v1/portfolio/risks", {
  headers: { Authorization: "Bearer <your-api-key>" }
});
const { data: risks } = await res.json();
risks.forEach(r => console.log(r.account.name, r.diagnostic.severity_display));

Pagination

Lists use cursor-based pagination. Parameters:limit (default 20, max 100) andcursor (opaque, provided by the response).

# Page 1
GET /accounts?limit=10

# Page 2: reuse meta.next_cursor from the previous response
GET /accounts?limit=10&cursor=eyJkYSI6IjIwMjYt...

When meta.next_cursor is null, you have reached the last page.

Path 2

MCP (AI agents)

The same backend exposed as tools the agent calls on its own, over JSON-RPC, without writing code.

MCP configuration

MCP (Model Context Protocol) is an open protocol that connects an AI agent to data sources. Phano exposes 6 tools the assistant calls on its own. Transport: HTTP POST (JSON-RPC) on https://phano.ai/api/v1/mcp, authenticated with the same API key.

Option A: client with remote HTTP support (recommended)

For clients that handle a remote MCP server with a header: Cursor, VS Code, Windsurf, Cline, n8n, or any MCP SDK. Add this block to the tool's MCP configuration.

{
  "mcpServers": {
    "phano": {
      "url": "https://phano.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Option B: local client without remote headers (Claude Desktop)

Claude Desktop does not send an authentication header to a remote server. Go through the mcp-remote bridge, which injects the key.

{
  "mcpServers": {
    "phano": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://phano.ai/api/v1/mcp",
        "--header", "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

Option C: test the connection (curl)

Check that the key works by listing the tools, without any client.

curl -X POST https://phano.ai/api/v1/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available tools

Tool	Required scope	Description
phano_getPortfolioSummary	read:portfolio	Portfolio summary: ARR, health, renewals, active diagnostics.
phano_getPortfolioRisks	read:portfolio	At-risk accounts sorted by severity and confidence.
phano_getAccounts	read:accounts	Account list with filters.
phano_getAccountIntelligence	read:accounts	Full intelligence for one account.
phano_getAccountStakeholders	read:stakeholders	Key contacts and champions of one account.
phano_getStatus	read:all	Instance health: latest composite run, connections.

6 tools: phano_getPortfolioSummary, phano_getPortfolioRisks, phano_getAccounts, phano_getAccountIntelligence, phano_getAccountStakeholders, phano_getStatus.

Examples

Integration recipes

A few concrete scenarios, on the REST side as well as the MCP side.

Integration recipes

At-risk account detected, alert in your communication tool (poll /portfolio/risks)
Expansion signal, notification to the Account Manager who owns the account
Daily portfolio summary, export to your spreadsheet or your data warehouse
AI agent answering the CS team's questions through the MCP tools

No-code tools: Zapier, Make, n8n through an HTTP webhook action with the Authorization header. Spreadsheets: Google Sheets (Apps Script), Excel (Power Query).