Chambrée
API/API Outils

API Outils

Découvrir et exécuter les outils d'une organisation depuis un registre unique.

Chaque outil d'organisation est déclaré une seule fois dans convex/tools/definitions/, puis exposé sur trois surfaces : cette API REST, le serveur MCP et la commande pnpm tools. Ajouter un outil au registre le publie partout en même temps.

Points d'entrée

GET  /api/v1/tools
GET  /api/v1/tools/:name
POST /api/v1/tools/:name
Point d'entréeDescription
GET /api/v1/toolsListe tous les outils avec leur schéma JSON
GET /api/v1/tools/:nameSchéma JSON d'un seul outil
POST /api/v1/tools/:nameExécute un outil, le corps JSON servant d'entrée

Authentification

Créez une clé d'API d'organisation depuis les réglages de l'organisation :

/orgs/{orgSlug}/settings/api-keys

Envoyez-la dans l'en-tête x-api-key ou comme jeton porteur :

x-api-key: VOTRE_CLE_API
Authorization: Bearer VOTRE_CLE_API

La clé détermine l'organisation : aucun identifiant d'organisation n'est jamais passé dans l'entrée d'un outil.

Un jeton d'accès OAuth délivré à un client MCP s'envoie de la même façon, comme jeton porteur. Les clés d'API se reconnaissent à leur préfixe chb_, tout le reste est vérifié comme un jeton OAuth : les deux moyens d'authentification aboutissent aux mêmes gestionnaires.

Outils disponibles

OutilCatégorieAccèsEntréeRetour
get_organizationorganizationlectureaucuneIdentifiant, nom et slug de l'organisation
list_membersmemberslecture{ cursor?, limit? }{ members, count, nextCursor, hasMore }
get_membermemberslecture{ memberId }Un membre
get_subscriptionbillinglectureaucuneFormule, statut, sièges et limites du plan

Réponse de découverte

GET /api/v1/tools renvoie un schéma JSON par outil, directement exploitable par un modèle de langage ou un générateur de client :

{
  "total": 4,
  "tools": [
    {
      "name": "get_member",
      "description": "Get a single organization member by member id. Use list_members to discover ids.",
      "category": "members",
      "access": "read",
      "inputSchema": {
        "type": "object",
        "properties": {
          "memberId": { "type": "string", "minLength": 1 }
        },
        "required": ["memberId"]
      },
      "endpoint": "/api/v1/tools/get_member",
      "method": "POST",
      "route": { "method": "GET", "path": "/api/v1/members/:memberId" }
    }
  ]
}

route est l'alias REST de l'outil, ou null quand il ne répond que sur /api/v1/tools/<nom>. Les deux chemins exécutent le même outil ; l'alias renvoie la charge utile sans l'enveloppe data.

Réponse d'exécution

Une exécution réussie renvoie la charge utile de l'outil sous data :

{
  "data": {
    "members": [{ "id": "member_123", "role": "owner" }],
    "count": 1,
    "nextCursor": null,
    "hasMore": false
  }
}

Ligne de commande

export CHAMBREE_API_KEY="VOTRE_CLE_API"
pnpm tools list
pnpm tools run get_member '{"memberId":"member_123"}'

MCP

Le serveur MCP est monté sur /api/mcp et sert le même registre. Il s'authentifie avec la même clé d'API d'organisation :

{
  "mcpServers": {
    "chambree": {
      "url": "https://chambree.fr/api/mcp",
      "headers": { "Authorization": "Bearer VOTRE_CLE_API" }
    }
  }
}

OAuth pour MCP

Les clients qui ne peuvent pas stocker de clé d'API (connecteurs ChatGPT, Claude, MCP Inspector) se connectent en OAuth. Pointez le client sur /api/mcp sans identifiants : il découvre tout ce dont il a besoin.

  1. La requête non authentifiée répond 401 avec un en-tête WWW-Authenticate qui pointe vers /.well-known/oauth-protected-resource/api/mcp.
  2. Ce document désigne le serveur d'autorisation, /api/auth, dont les métadonnées sont servies depuis /.well-known/oauth-authorization-server.
  3. Le client s'enregistre dynamiquement, puis fait passer l'utilisateur par la connexion, le choix de l'organisation (/auth/oauth/select-organization) et le consentement (/auth/oauth/consent).
  4. Le jeton d'accès délivré est un JWT qui porte l'organization_id retenu : il est donc limité à une seule organisation, exactement comme une clé d'API.
PortéeDonne accès à
chambree.readTous les outils en lecture et les points d'entrée de découverte
chambree.writeNécessaire en plus de chambree.read pour les outils en écriture

Seuls les propriétaires et les administrateurs peuvent autoriser une connexion. Un jeton sans chambree.write reçoit un 403 s'il appelle un outil en écriture.

Les jetons d'accès sont de courte durée. À l'expiration, le client relance le flux de code d'autorisation : le rôle dans l'organisation et le consentement sont donc revérifiés avant qu'un nouveau jeton soit délivré.

Erreurs

StatutDescription
400Corps JSON invalide, ou entrée qui ne respecte pas le schéma
401Clé ou jeton d'accès manquant, invalide ou expiré
403Jeton valide mais dépourvu de la portée exigée par l'outil
404Outil inconnu, ou ressource introuvable
413Corps de requête supérieur à 256 Ko
500Erreur interne du serveur
API Membre d'une organisation