Riferimento API

Il riferimento API completo sarà auto-generato dalla nostra spec OpenAPI 3.1 nel momento in cui la superficie sarà stabile. Preferiamo shippare un placeholder piuttosto che fake-doc endpoint che possono ancora muoversi. Nel frattempo, ecco la forma, cosa coprirà e cosa fare oggi.

Forma (soggetta a cambiamenti)

REST su HTTPS. JSON in, JSON out. Auth via Bearer token su ogni richiesta. Versionato nel path: /v1/.... Rate-limit per token; la risposta porta i soliti header X-RateLimit-*.

curl

1# ogni endpoint prende una API key nell'header Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

Le API key vengono da Org Settings → API Keys nella dashboard. La stessa key funziona per la CLI, il server MCP e le chiamate REST dirette — l'API consuma solo il bearer.

Risorse che vedrai al lancio

Queste sono le risorse che l'API V1 esporrà. La forma esatta — campi, codici d'errore, paginazione — atterra quando pubblicheremo la spec OpenAPI.

Risorsa	Cosa rappresenta	Ops V1
Projects	Workspace. Create, list, archive, transfer ownership.	GET · POST · PATCH · DELETE
Locales	Set di locali con scope di progetto. Aggiungi un locale, segnalo come default, abilita/disabilita per i client.	GET · POST · PATCH · DELETE
Namespaces	Bucket logici di chiavi per progetto (es. "checkout", "common").	GET · POST · PATCH · DELETE
Keys	Chiavi di traduzione con la loro descrizione, URL di screenshot, max-length, regole di plurale.	GET · POST · PATCH · DELETE
Translations	Valore per locale di una chiave. Stati draft, in-review, approved; storia delle revisioni.	GET · POST · PATCH · DELETE
Missing keys	La coda dell'SDK runtime. List, group by frequency, marca come triata.	GET · PATCH
Webhooks	Iscriviti agli event di traduzione. V2.	V2

Cosa fare oggi

Praticamente tutto per cui ricorreresti all'API è già esposto via la CLI, il server MCP o l'SDK runtime. Usali — quando l'API shippa, il tuo codice può passare a chiamate HTTP dirette senza cambiare quello che fa davvero.

CLI

@verbumia/cli

Push, pull, import, export — copre la maggior parte delle esigenze di automazione.

MCP

Configura Claude Desktop

Leggi chiavi, proponi traduzioni, revisiona diff di PR da qualsiasi agente.

SDK

React + i18next

Leggi traduzioni e cattura chiavi mancanti nel tuo runtime.

Riferimento

Tutte le docs

Indice di tutto quello che abbiamo pubblicato finora.

OpenAPI live per early dev

Se stai facendo girare il backend Verbumia in locale, la spec OpenAPI 3.1 live è esposta a:

backend locale

http://localhost:8820/openapi.json

Punta Stoplight, Swagger UI, Insomnia, Postman o qualsiasi tool compatibile OpenAPI a quell'URL. La forma si muove — per questo questa pagina è un placeholder — ma è la source of truth in questo momento se vuoi esplorare gli endpoint in anticipo.

Quando atterra il riferimento pubblico?

La spec OpenAPI pubblica sarà servita a https://api.verbumia.ca/openapi.json non appena la superficie V1 sarà congelata. Da lì, questa pagina passerà da placeholder a un riferimento renderizzato per intero (Stoplight o un viewer simile sopra la spec) — niente copy di marketing, solo ogni endpoint, ogni payload, ogni codice d'errore, generato dalla sorgente.