Documentation API et MCP

Toutes les requêtes (REST et MCP) s'authentifient avec la même clé, dans le headerAuthorization :

Authorization: Bearer pk_live_xxxx

Créez la clé dans Paramètres > Clés API (affichée une seule fois). Les scopes déterminent ce que la clé peut lire. Une clé sansread:stakeholdersreçoit les comptes et diagnostics, mais les noms des contacts sont masqués.

Format stable : { "error": { "code", "message" } }. En MCP, ces erreurs sont renvoyées via les codes JSON-RPC correspondants (par exemple scope insuffisant = -32003).

3 niveaux de limitation :

• Burst : 50 requêtes / 10 secondes par clé
• Quotidien : 10 000 requêtes / jour par organisation
• Circuit breaker : 429 temporaire (Retry-After 60s) si plus de 50% d'erreurs 5xx sur 1 minute

En-têtes de réponse :

• X-RateLimit-Limit : limite burst
• X-RateLimit-Remaining : requêtes restantes
• X-RateLimit-Reset : epoch de reset
• X-RateLimit-Limit-Daily : quota quotidien (10 000)
• Retry-After : secondes avant retry (si 429)

Base : https://phano.ai/api/v1. Le contrat machine complet (schémas de réponse, types) est sur openapi.json.

# 1. Lister les comptes (récupérer un id)
curl -H "Authorization: Bearer <votre-cle-api>" \
  "https://phano.ai/api/v1/accounts?limit=5"

# 2. Intelligence d'un compte précis
curl -H "Authorization: Bearer <votre-cle-api>" \
  https://phano.ai/api/v1/accounts/<id>/intelligence

import requests

headers = {"Authorization": "Bearer <votre-cle-api>"}
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']}")

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

Les listes utilisent une pagination cursor-based. Paramètres :limit (défaut 20, max 100) etcursor (opaque, fourni par la réponse).

# Page 1
GET /accounts?limit=10

# Page 2 : réutilisez meta.next_cursor de la réponse précédente
GET /accounts?limit=10&cursor=eyJkYSI6IjIwMjYt...

Quand meta.next_cursor vaut null, c'est la dernière page.

Le MCP (Model Context Protocol) est un protocole ouvert qui connecte un agent IA à des sources de données. Phano expose 8 outils que l'assistant appelle lui-même. Transport : HTTP en POST (JSON-RPC) sur https://phano.ai/api/v1/mcp, authentifié par la même clé API.

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

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

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

8 outils : phano_getPortfolioSummary, phano_getPortfolioRisks, phano_getAccounts, phano_getAccountIntelligence, phano_getAccountStakeholders, phano_getAccountMemory, phano_getRevenueAtRisk, phano_getStatus.

• Compte à risque détecté, alerte dans votre outil de communication (poll de /portfolio/risks)
• Signal d'expansion, notification à l'Account Manager concerné
• Résumé portefeuille quotidien, export vers votre tableur ou votre data warehouse
• Agent IA qui répond aux questions de vos équipes à partir des outils MCP

Outils no-code : Zapier, Make, n8n via une action webhook HTTP avec le header Authorization. Tableurs : Google Sheets (Apps Script), Excel (Power Query).