Référence API

La référence API complète sera auto-générée à partir de notre spec OpenAPI 3.1 dès que la surface sera stable. On préfère shipper un placeholder plutôt que de fake-doc des endpoints qui peuvent encore bouger. En attendant, voici la forme, ce que ça couvrira, et quoi utiliser aujourd'hui.

Forme (sujette à changement)

REST sur HTTPS. JSON en entrée, JSON en sortie. Header Authorization: ApiKey <prefix>.<secret> sur chaque requête. Versionné dans le path : /v1/.... Rate-limit par token ; la réponse porte les headers X-RateLimit-* habituels.

curl

1# chaque endpoint prend une clé API dans le header Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

Les clés API viennent de Org Settings → API Keys dans le dashboard. La même clé fonctionne pour la CLI, le serveur MCP, et les appels REST directs — l'API consomme juste le bearer.

Ressources au lancement

Voici les ressources que l'API V1 exposera. La forme exacte — champs, codes d'erreur, pagination — sera figée à la publication de la spec OpenAPI.

Ressource	Ce que ça représente	Ops V1
Projects	Workspaces. Create, list, archive, transfer d'ownership.	GET · POST · PATCH · DELETE
Locales	Set de locales scopé au projet. Ajouter une locale, marquer comme défaut, activer/désactiver pour les clients.	GET · POST · PATCH · DELETE
Namespaces	Buckets logiques de clés par projet (ex. « checkout », « common »).	GET · POST · PATCH · DELETE
Keys	Clés de traduction avec leur description, URLs de screenshot, max-length, règles de pluriel.	GET · POST · PATCH · DELETE
Translations	Valeur par locale d'une clé. États draft / in-review / approved ; historique de révisions.	GET · POST · PATCH · DELETE
Missing keys	La file du SDK runtime. List, group by frequency, marquer triagé.	GET · PATCH
Webhooks	S'abonner aux events de traduction. V2.	V2

Quoi faire aujourd'hui

À peu près tout ce pour quoi vous appelleriez l'API est déjà exposé via la CLI, le serveur MCP, ou le SDK runtime. Utilisez-les — quand l'API shippe, votre code pourra basculer vers des appels HTTP directs sans changer ce qu'il fait vraiment.

CLI

@verbumia/cli

Push, pull, import, export — couvre la plupart des besoins d'automatisation.

MCP

Configurer Claude Desktop

Lire les clés, proposer des traductions, réviser les diffs de PR depuis n'importe quel agent.

SDK

React + i18next

Lire les traductions et capturer les clés manquantes dans votre runtime.

Référence

Toutes les docs

Index de tout ce qu'on a publié jusqu'à maintenant.

OpenAPI live pour early devs

Si vous lancez le backend Verbumia en local, la spec OpenAPI 3.1 live est exposée à :

backend local

http://localhost:8820/openapi.json

Pointez Stoplight, Swagger UI, Insomnia, Postman, ou n'importe quel outil compatible OpenAPI sur cette URL. La forme bouge — c'est pourquoi cette page est un placeholder — mais c'est la source de vérité maintenant si vous voulez explorer les endpoints en avance.

Quand la référence publique arrive ?

La spec OpenAPI publique sera servie à https://api.verbumia.ca/openapi.json dès que la surface V1 sera figée. À ce moment, cette page passera de placeholder à une référence rendue intégralement (Stoplight ou un viewer similaire au-dessus de la spec) — pas de marketing, juste chaque endpoint, chaque payload, chaque code d'erreur, généré depuis la source.