For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /fr/docs/modules/api.md (or send Accept: text/markdown).

Module API

Le contrat public versionné, la plomberie des clés et la surface OpenAPI.

Poser une question sur ce guide

Avant de commencer

Ouvrez votre projet supastack téléchargé dans Visual Studio Code en utilisant Fichier → Ouvrir le dossier, puis choisissez Terminal → Nouveau terminal. La racine du référentiel est le dossier contenant package.json, les applications et les packages. Exécutez la commande ci-dessous et laissez son terminal ouvert. Si une commande n'est pas reconnue, terminez le guide d'installation de l'outil avant de continuer.

Lisez d’abord le didacticiel de la plateforme. Un serveur est le processus d'application qui répond aux requêtes du navigateur ou du téléphone. Le Web lit apps/web/.env.local, Expo lit apps/mobile/.env.local et les commandes de migration de base de données lisent root .env. La démonstration sans base de données/tableau de bord est distincte des comptes réels/auth, qui nécessitent une migration Postgres. Un paiement sur téléphone ou sur ordinateur uniquement nécessite un backend Web exécuté séparément.

corepack pnpm --filter @supastack/web dev

Configuration et paramètres

packages/api est la source de vérité pour la surface REST publique : schémas zod pour les requêtes, réponses et l'enveloppe d'erreur, plus le document OpenAPI (openApiDocument) servi à /api/v1/openapi. Les handlers de route composent ces schémas au lieu de redéfinir des formes.

Les clés API sont émises par workspace avec un préfixe sk_<env>_, stockées hachées avec comparaison en temps constant, et portent des scopes — lecture par défaut. api-keys.ts possède la création, la recherche et la révocation.

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

Processus d’implémentation

Ajoutez des endpoints dans la version existante : étendez les schémas, gardez l'enveloppe d'erreur, et régénérez la surface OpenAPI pour que /api/docs reste exact. Les changements cassants obtiennent une nouvelle version, pas un changement de forme silencieux.

Résolvez le workspace de l'appelant depuis la clé présentée, appliquez les mêmes règles d'entitlement et de validation que l'app web, et rate-limitez par clé.

Vérification et dépannage

Contract-testez chaque forme de route contre les schémas du package. Vérifiez que les clés inconnues, révoquées et les requêtes sous-scopées échouent toutes avec l'enveloppe d'erreur documentée, et que le document OpenAPI reste du JSON valide.