Tools RPC (/v1/rpc/tools)

L’API Tools RPC est une surface alternative à REST /v1, pensée pour les agents IA et les outils d’automatisation.

Au lieu d’un endpoint par ressource, tout passe par POST /v1/rpc/tools/{name}, avec les paramètres dans le corps. Presque le même catalogue d’outils que le serveur MCP, exposé en HTTP standard : les écarts sont listés dans Tools disponibles.

Pourquoi cette surface

• Zapier, Make et n8n ont un nœud « HTTP Request » générique : un outil = un appel.
• OpenAI Assistants et le function calling associent une opération OpenAPI à une fonction.
• Les traitements par lot : les outils de lot (get_companies, get_financials_batch…) ne sont servis que sur cette surface.

Quick start

1. Lister les outils disponibles

curl https://api.insourcia.io/v1/rpc/tools \
  -H "Authorization: Bearer isk_VOTRE_CLE"

Réponse :

{
  "tools": [
    {
      "name": "search_companies",
      "description": "Recherche d'entreprises françaises par nom, SIREN, activité...",
      "inputSchema": { "type": "object", "properties": { "query": {...} }, ... }
    },
    ...
  ]
}

2. Invoquer un outil

curl -X POST https://api.insourcia.io/v1/rpc/tools/search_companies \
  -H "Authorization: Bearer isk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"query":"vinci","limit":3}'

Réponse (enveloppe JSend) :

{
  "success": true,
  "data": {
    "data": [
      { "siren": "552037806", "denomination": "VINCI", ... }
    ],
    "pagination": { "total": 1, "limit": 3, "has_more": false }
  }
}

Erreur de paramètre (le détail suit le format de validation, il peut varier) :

{
  "success": false,
  "error": "Invalid input",
  "details": [{ "path": ["query"], "message": "Invalid input: expected string, received undefined" }]
}

Clé absente ou invalide (401) :

{
  "error": "unauthorized",
  "message": "Invalid or missing API key.",
  "message_fr": "Clé API invalide ou manquante."
}

Tools disponibles

25 outils sur la surface Tools RPC. Référence interactive avec try-it-now sur /docs/tools.

Absents du serveur MCP : get_companies, get_financials_batch, get_credit_risks, get_directors_batch, get_events_batch, get_company_graphs.

Propres au serveur MCP : reveal_director_email, get_account.

Découverte

Tool	Action	Détail
search_companies	Recherche d'entreprises	Filtres par secteur, géographie, taille, dirigeant, et agrégats financiers (CA, EBE, dette, trésorerie). Composés en langage naturel.
resolve_companies	Rapprochement d'un fichier	Rattache en lot des fiches mal identifiées (export CRM, tableur, fichier client) à leur SIREN. À la différence d'une recherche, l'outil refuse de trancher quand l'identification est incertaine et le signale, au lieu de rendre un « meilleur résultat » par défaut.
search_directors	Recherche de dirigeants	Retrouve une personne physique par son nom de famille à travers toutes les entreprises françaises.
search_director_companies	Empreinte d'un dirigeant	Toutes les sociétés où une personne détient un mandat direct, désambiguïsée par nom, prénom et date de naissance.

Profil

Tool	Action	Détail
get_company	Fiche société	Identité, activité, effectifs, dirigeants, immatriculation, codes NAF.
get_directors	Dirigeants & mandats	Dirigeants d'une société, leur rôle et la structure hiérarchique des mandats.
get_company_graph	Cartographie de groupe	Graphe orienté des entités autour d'une société : holdings, filiales, sociétés sœurs, dirigeants communs.

Finance

Tool	Action	Détail
get_financials	Bilans & comptes annuels	Compte de résultat, bilan, ratios (trésorerie, dette nette, BFR, marges, délais de paiement), dividendes versés, sur plusieurs exercices consécutifs.
get_credit_risk	Score de risque crédit	Grade de AAA à D, probabilité de défaut à 3, 6 et 12 mois, et les cinq principaux facteurs aggravants ou atténuants.

Veille légale

Tool	Action	Détail
search_events	Recherche d'événements	Événements toutes sociétés confondues : cessions de fonds, procédures collectives, dépôts de comptes, augmentations de capital, marchés publics, subventions, radiations, créations.
get_events	Timeline d'une société	Tous les événements d'une société donnée, classés dans le temps.

Traitement en lot

Tool	Action	Détail
get_companies	Fiches en lot	Le contenu de la fiche société pour dix SIREN à la fois.
get_financials_batch	Historiques financiers en lot	L'historique chiffré de plusieurs sociétés en un appel : dix en format compact, trois en format détaillé.
get_credit_risks	Scores de risque en lot	Le score de risque crédit de dix sociétés à la fois.
get_directors_batch	Dirigeants en lot	Les dirigeants de dix sociétés à la fois, vingt mandats par société.
get_events_batch	Événements en lot	Les vingt derniers événements de dix sociétés à la fois.
get_company_graphs	Cartographies de groupe en lot	Le graphe de détention et de mandats de plusieurs sociétés en un appel.

Surveillance

Tool	Action	Détail
create_saved_search	Recherche sauvegardée	Enregistre des critères pour suivre un secteur ou un portefeuille de sociétés dans le temps, avec alerte.
list_saved_searches	Mes recherches sauvegardées	Les recherches suivies par votre compte, telles qu'elles apparaissent dans l'app.
watch_company	Mise sous surveillance	Ajoute une société à une liste de veille : ses nouveaux événements remontent ensuite dans l'app.
list_watched_companies	Mes sociétés surveillées	Les sociétés déjà sous surveillance dans vos listes de veille.
unwatch_company	Retirer de la surveillance	Retire une société d'une liste de veille : ses événements cessent de remonter.
set_list_monitoring	Activer ou couper la veille d'une liste	Active ou coupe la surveillance d'une liste. Une liste dont la veille est coupée ne compte plus dans la limite de sociétés surveillées.
get_news	Fil de veille	Ce qui a bougé sur vos sociétés surveillées : changements de dirigeants, procédures collectives, cessions, radiations, les plus récents d'abord. Filtrable sur les signaux non lus.
mark_news_read	Signaux traités	Marque comme lus les signaux du fil de veille que vous avez traités, pour que la prochaine lecture ne les remonte plus.

La révélation d’email, absente de cette surface, s’appelle en REST : POST /v1/companies/directors/reveal-email, décrite dans la référence API.

OpenAPI 3.1

Spécification téléchargeable, conforme au standard :

https://api.insourcia.io/v1/rpc/tools/openapi.json

Importable dans Postman, n8n, Insomnia, etc.

Authentification

Bearer token, identique à REST :

Authorization: Bearer isk_VOTRE_CLE

Limites de débit et accès

Mêmes règles que /v1 : rate limit par clé API, débit en crédits selon la même grille, et données réservées aux abonnés. Le passage par Tools RPC ne contourne rien. Coûts par opération et erreurs de solde : Tarification et crédits.