API des outils
Découvrez et exécutez les outils d’une organisation depuis un registre unifié.
Chaque outil est déclaré une seule fois dans convex/tools/definitions/, puis exposé par l’API REST, le serveur MCP et la CLI pnpm tools. Son ajout au registre le publie sur les trois interfaces.
Points d’entrée
GET /api/v1/tools
GET /api/v1/tools/:name
POST /api/v1/tools/:name| Point d’entrée | Description |
|---|---|
GET /api/v1/tools | Liste les outils et leurs schémas JSON |
GET /api/v1/tools/:name | Renvoie le schéma JSON d’un outil |
POST /api/v1/tools/:name | Exécute un outil avec un corps JSON |
Authentification
Créez une clé API depuis les paramètres de l’organisation :
/orgs/{orgSlug}/settings/api-keysEnvoyez-la avec x-api-key ou comme jeton Bearer :
x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEYLa clé identifie l’organisation : aucun identifiant d’organisation ne doit figurer dans l’entrée d’un outil.
Un jeton OAuth fourni à un client MCP est envoyé de la même façon. Le préfixe nsk_ identifie les clés API ; les autres valeurs sont vérifiées comme des jetons OAuth. Les deux passent par les mêmes handlers.
Outils disponibles
| Outil | Catégorie | Accès | Entrée | Résultat |
|---|---|---|---|---|
get_organization | organization | read | aucune | Identifiant, nom et slug |
list_members | members | read | { cursor?, limit? } | { members, count, nextCursor, hasMore } |
get_member | members | read | { memberId } | Un membre |
get_subscription | billing | read | aucune | Offre, statut, sièges et limites |
Réponse de découverte
GET /api/v1/tools renvoie un schéma JSON par outil, prêt pour un LLM ou un générateur de client :
{
"total": 4,
"tools": [
{
"name": "get_member",
"description": "Récupère un membre de l’organisation par son identifiant.",
"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 contient l’alias REST, ou null si l’outil répond uniquement sur /api/v1/tools/<name>. Les deux chemins exécutent le même outil ; l’alias renvoie le contenu sans l’enveloppe data. Consultez Outils unifiés pour en déclarer un.
Réponse d’exécution
Une exécution réussie renvoie le résultat dans data :
{
"data": {
"members": [{ "id": "mem_123", "role": "owner" }],
"count": 1,
"nextCursor": null,
"hasMore": false
}
}CLI
export NOWSTACK_API_KEY="YOUR_API_KEY"pnpm tools list